qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/execution/dream-agent.js

@@ -0,0 +1,974 @@
+/**
+ * Dream Sub-agent — CC autoDream parity.
+ *
+ * Memory consolidation runs as a restricted sub-agent:
+ *   - Read-only tool access (bash: ls/grep/cat/find/stat/wc/head/tail)
+ *   - File writes restricted to memory directory
+ *   - 4-phase system prompt: Orient → Gather → Consolidate → Prune
+ *   - Trigger gates: time (24h) + session count (5)
+ *   - PID-based consolidation lock
+ *
+ * Reference: claude-code src/services/autoDream/
+ */
+import { readFile, writeFile, stat, unlink, mkdir } from "node:fs/promises";
+import { join, resolve, isAbsolute, normalize } from "node:path";
+import { randomUUID } from "node:crypto";
+import { runForkedAgent } from "./forked-agent.js";
+import { scanCategoryManifest, formatCategoryContextBlock } from "./dream-category-context.js";
+// ── Defaults ────────────────────────────────────────────────
+const DEFAULT_TRIGGER = {
+    minHours: 24,
+    minSessions: 5,
+    minTurnsInSession: 20,
+    scanIntervalMs: 600_000, // 10 min
+};
+// Liveness lock: held only WHILE a dream runs. Separate from the gate marker
+// below, so reclaiming a dead lock never corrupts the "last consolidated" time.
+const LOCK_FILE = ".consolidate-lock";
+// Hard run ceiling: a real dream completes in minutes. If the lock mtime is
+// older than this, the holder is presumed dead (crash / PID reuse) and the lock
+// is reclaimable regardless of the recorded PID. A running dream heartbeats the
+// lock mtime, so a legitimate long dream is NOT reclaimed.
+const MAX_DREAM_RUN_MS = 15 * 60 * 1000;
+// Heartbeat cadence — keeps a live dream's lock fresh well within MAX_DREAM_RUN_MS.
+const LOCK_HEARTBEAT_MS = 60 * 1000;
+// Gate marker: mtime = time of the last SUCCESSFUL consolidation. Drives the
+// 24h/session trigger gates. Only markConsolidationComplete touches it.
+const LAST_CONSOLIDATED_FILE = ".last-consolidated";
+const ENTRYPOINT_NAME = "CLAUDE.md";
+const MAX_ENTRYPOINT_LINES = 100;
+// ── Read-only command detection (CC BashTool.isReadOnly parity) ──
+const READ_ONLY_COMMANDS = new Set([
+    "ls", "find", "grep", "cat", "stat", "wc", "head", "tail",
+    "file", "which", "whereis", "type", "echo", "printf", "test",
+    "diff", "sort", "uniq", "tr", "cut", "awk", "sed", // sed -n only
+    "du", "df", "date", "pwd", "hostname", "uname",
+    "git", // read-only git subcommands checked separately
+]);
+const GIT_READ_ONLY_SUBCOMMANDS = new Set([
+    "log", "show", "diff", "status", "branch", "tag", "remote",
+    "rev-parse", "rev-list", "ls-files", "ls-tree", "describe",
+    "blame", "shortlog", "name-rev", "cat-file",
+]);
+/** Dangerous patterns that indicate a write operation. */
+const WRITE_INDICATORS = /[|>&]|>>|>\s|rm\s|mv\s|cp\s|chmod\s|chown\s|mkdir\s|touch\s/;
+/**
+ * Check if a bash command string is read-only.
+ * Conservative: denies anything with pipes, redirects, or unknown commands.
+ */
+function isReadOnlyBashCommand(command) {
+    const trimmed = command.trim();
+    // Deny empty
+    if (!trimmed)
+        return false;
+    // Deny anything with obvious write indicators
+    if (WRITE_INDICATORS.test(trimmed))
+        return false;
+    // Parse first word as the command
+    const parts = trimmed.split(/\s+/);
+    const cmd = parts[0]?.replace(/^(\/usr\/bin\/|\/bin\/|\/usr\/local\/bin\/)/, "") ?? "";
+    if (!READ_ONLY_COMMANDS.has(cmd))
+        return false;
+    // Special case: git needs subcommand check
+    if (cmd === "git") {
+        const subCmd = parts[1];
+        if (!subCmd || !GIT_READ_ONLY_SUBCOMMANDS.has(subCmd))
+            return false;
+    }
+    return true;
+}
+async function persistDreamSummaryArtifact(params) {
+    await mkdir(params.memoryRoot, { recursive: true });
+    const summaryPath = join(params.memoryRoot, "fact-dream-summary.md");
+    let finalContent;
+    for (const event of params.events) {
+        if (event.type !== "end")
+            continue;
+        const content = event.content.trim();
+        if (content.length > 0)
+            finalContent = content;
+    }
+    const touched = [...new Set(params.filesTouched)];
+    const lines = [
+        "# Dream Consolidation Summary",
+        "",
+        `- completedAt: ${new Date().toISOString()}`,
+        `- sessionsReviewed: ${params.sessionsReviewed}`,
+        `- durationMs: ${params.durationMs}`,
+        "",
+        "## Agent Summary",
+        "",
+        finalContent || "Dream completed without a textual model summary.",
+        ...(params.sessionDigest ? [
+            "",
+            "## Recent Session Digest",
+            "",
+            params.sessionDigest,
+        ] : []),
+        "",
+        "## Files Touched",
+        "",
+        ...(touched.length > 0 ? touched.map((file) => `- ${file}`) : ["- none"]),
+        "",
+    ];
+    await writeFile(summaryPath, lines.join("\n"), "utf8");
+    return summaryPath;
+}
+function safeSessionId(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+async function readSessionDigest(transcriptDir, sessionIds) {
+    const sections = [];
+    for (const sessionId of sessionIds.slice(0, 8)) {
+        const transcriptPath = join(transcriptDir, safeSessionId(sessionId), "transcript.jsonl");
+        let raw = "";
+        try {
+            raw = await readFile(transcriptPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const entries = [];
+        for (const line of raw.trim().split(/\r?\n/).slice(-24)) {
+            try {
+                const record = JSON.parse(line);
+                if (typeof record.content !== "string" || record.content.trim().length === 0)
+                    continue;
+                const role = typeof record.role === "string" ? record.role : "message";
+                entries.push(`${role}: ${record.content.replace(/\s+/g, " ").slice(0, 900)}`);
+            }
+            catch {
+                continue;
+            }
+        }
+        if (entries.length > 0) {
+            sections.push(`### Session ${sessionId}\n${entries.join("\n")}`);
+        }
+    }
+    return sections.join("\n\n").slice(0, 16_000);
+}
+// ── Tool restriction (CC createAutoMemCanUseTool parity) ────
+/**
+ * Check if a tool invocation is allowed during dream consolidation.
+ *
+ * Allowed:
+ *   - read_file, grep, glob, search — unrestricted read-only tools
+ *   - bash — only read-only commands (ls, grep, cat, find, stat, wc, head, tail)
+ *   - file_edit, file_write — only within memoryRoot
+ *   - Everything else — denied
+ */
+export function canUseDreamTool(memoryRoot, restriction) {
+    const { toolName, input } = restriction;
+    // Always-allow: read-only tools (qlogicagent canonical names)
+    const readOnlyTools = new Set([
+        "read", "search",
+        // LLM tool name variants (models may emit these instead of canonical names)
+        "read_file", "grep", "glob", "list_dir", "file_read", "Grep", "Glob",
+    ]);
+    if (readOnlyTools.has(toolName)) {
+        return { allowed: true };
+    }
+    // QMemory tools: allowed during dream (hippocampus bridge)
+    const qmemoryTools = new Set([
+        "qmemory_search", "qmemory_store", "qmemory_feedback", "qmemory_temporal", "qmemory_profile",
+    ]);
+    if (qmemoryTools.has(toolName)) {
+        return { allowed: true };
+    }
+    // Shell exec: only read-only commands (qlogicagent name: "exec")
+    if (toolName === "exec" || toolName === "bash" || toolName === "execute_command" || toolName === "Bash") {
+        const command = (input.command ?? input.cmd ?? "");
+        if (isReadOnlyBashCommand(command)) {
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            reason: "Only read-only shell commands are permitted during dream consolidation "
+                + "(ls, find, grep, cat, stat, wc, head, tail, and similar)",
+        };
+    }
+    // File write/edit/patch: only within memory directory (qlogicagent names: "write", "edit", "patch")
+    if (toolName === "write" || toolName === "edit" || toolName === "patch"
+        || toolName === "file_edit" || toolName === "file_write" || toolName === "FileEdit" || toolName === "FileWrite") {
+        const filePath = (input.file_path ?? input.path ?? input.filePath ?? "");
+        if (typeof filePath === "string" && isWithinMemoryDir(filePath, memoryRoot)) {
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            reason: `File writes are only allowed within the memory directory: ${memoryRoot}`,
+        };
+    }
+    // Everything else: denied
+    return {
+        allowed: false,
+        reason: `Tool "${toolName}" is not permitted during dream consolidation. `
+            + "Only read, search, read-only exec, and memory-scoped write/edit/patch are allowed.",
+    };
+}
+function isWithinMemoryDir(filePath, memoryRoot) {
+    const absPath = isAbsolute(filePath) ? filePath : resolve(filePath);
+    const absMemory = isAbsolute(memoryRoot) ? memoryRoot : resolve(memoryRoot);
+    const normalized = normalize(absPath);
+    const normalizedRoot = normalize(absMemory);
+    return normalized.startsWith(normalizedRoot);
+}
+// ── Consolidation Prompt (CC 4-phase parity) ────────────────
+/**
+ * Build the 4-phase memory consolidation prompt.
+ *
+ * Adapted from CC's consolidationPrompt.ts with our project context.
+ * P5: Enhanced with category-aware merge rules from write gate taxonomy.
+ */
+export function buildConsolidationPrompt(memoryRoot, transcriptDir, sessionIds, opts) {
+    const qmemorySection = opts?.hasQMemory ? `
+
+## Phase 2.5 — Long-term memory triage (QMemory)
+
+You have access to the long-term memory service via these tools:
+- \`qmemory_search\` — recall existing long-term memories (check before storing duplicates)
+- \`qmemory_store\` — submit a low-priority candidate to the memory consolidation pipeline
+- \`qmemory_feedback\` — mark recalled memories as outdated/wrong/useful
+
+For each insight worth long-term persistence:
+1. Search QMemory first to check for duplicates or contradictions
+2. If a contradiction is found, use qmemory_feedback to mark the old memory as "outdated"
+3. Submit the corrected/new candidate via qmemory_store; the consolidator decides whether it becomes an active claim, a merge, or a conflict
+
+Classify memories into:
+- **Project memory** → write to local memoryRoot/*.md (fast KV access, project-scoped)
+- **User long-term memory** → submit via qmemory_store (semantic search, persists across projects; not a direct final write)
+- **Noise** → discard (do not store)
+
+Examples of user long-term memories: preferences, personal facts, recurring patterns, important decisions.
+Examples of project memories: architecture decisions, file conventions, build patterns, known issues.
+` : "";
+    return `# Dream: Memory Consolidation
+
+You are performing a dream — a reflective pass over your memory files. Synthesize what you've learned recently into durable, well-organized memories so that future sessions can orient quickly.
+
+Memory directory: \`${memoryRoot}\`
+If the directory doesn't exist yet, create it with the necessary structure.
+
+Session transcripts: \`${transcriptDir}\` (large JSONL files — grep narrowly, don't read whole files)
+
+---
+
+## Phase 1 — Orient
+
+- \`ls\` the memory directory to see what already exists
+- Read \`${ENTRYPOINT_NAME}\` to understand the current index
+- Skim existing topic files so you improve them rather than creating duplicates
+- If \`logs/\` or \`sessions/\` subdirectories exist, review recent entries there
+
+## Phase 2 — Gather recent signal
+
+Look for new information worth persisting. Sources in rough priority order:
+
+1. **Session logs** if present — these are the append-only stream
+2. **Existing memories that drifted** — facts that contradict something in the codebase now
+3. **Transcript search** — if you need specific context, grep the JSONL transcripts for narrow terms:
+   \`grep -rn "<narrow term>" ${transcriptDir}/include="*.jsonl" | tail -50\`
+
+Don't exhaustively read transcripts. Look only for things you already suspect matter.
+${qmemorySection}${opts?.categoryContext ?? ""}${opts?.temporalContext ?? ""}${opts?.profileContext ?? ""}${opts?.sessionDigest ? `## Recent Session Digest
+
+The runtime already extracted this bounded digest from project transcripts. Treat it as primary evidence for consolidation:
+
+${opts.sessionDigest}
+
+` : ""}
+## Phase 2.8 — User Profile Update
+
+Analyze recent sessions for user preferences, habits, and personal context. Use two mechanisms:
+
+**Structured profile** (key-value, queryable): Use \`qmemory_profile\` with action "set" for discrete facts:
+- \`qmemory_profile(action="set", key="communication_style", value="concise, no fluff")\`
+- \`qmemory_profile(action="set", key="tech_stack", value="TypeScript, Node.js, Electron, SQLite")\`
+- \`qmemory_profile(action="set", key="work_schedule", value="late night coder, Asia/Shanghai")\`
+- \`qmemory_profile(action="set", key="project_context", value="AI desktop assistant monorepo")\`
+
+**Narrative memory candidates** (semantic search): Use \`qmemory_store\` with source "profile-extraction" for richer observations:
+- "User strongly dislikes over-engineering and unnecessary abstractions"
+- "User requires all code changes to compile before committing"
+
+Profile extraction rules:
+1. Read the existing profile first: \`qmemory_profile(action="get")\`
+2. Only update if you observe NEW or CHANGED information (don't duplicate)
+3. If an existing profile entry contradicts current behavior, update it
+4. Be specific and factual — avoid vague entries like "user is smart"
+5. Categories for profile keys: communication_style, tech_stack, work_schedule, project_context, coding_preferences, tools_used
+
+## Phase 3 — Consolidate
+
+For each thing worth remembering, write or update a memory file at the top level of the memory directory.
+
+Focus on:
+- Merging new signal into existing topic files rather than creating near-duplicates
+- Converting relative dates ("yesterday", "last week") to absolute dates so they remain interpretable after time passes
+- Deleting contradicted facts — if today's investigation disproves an old memory, fix it at the source
+
+## Phase 4 — Prune and index
+
+Update \`${ENTRYPOINT_NAME}\` so it stays under ${MAX_ENTRYPOINT_LINES} lines AND under ~25KB. It's an **index**, not a dump — each entry should be one line under ~150 characters: \`- [Title](file.md) — one-line hook\`. Never write memory content directly into it.
+
+- Remove pointers to memories that are now stale, wrong, or superseded
+- Demote verbose entries: if an index line is over ~200 chars, it's carrying content that belongs in the topic file — shorten the line, move the detail
+- Add pointers to newly important memories
+- Resolve contradictions — if two files disagree, fix the wrong one
+
+---
+
+**Tool constraints for this run:** Bash is restricted to read-only commands (\`ls\`, \`find\`, \`grep\`, \`cat\`, \`stat\`, \`wc\`, \`head\`, \`tail\`, and similar). Anything that writes, redirects to a file, or modifies state will be denied. Plan your exploration with this in mind — no need to probe.
+
+Sessions since last consolidation (${sessionIds.length}):
+${sessionIds.map(id => `- ${id}`).join("\n")}
+
+Return a brief summary of what you consolidated, updated, or pruned. If nothing changed (memories are already tight), say so.`;
+}
+// ── Trigger Gate Logic (CC autoDream parity) ─────────────────
+let lastSessionScanAt = 0;
+/**
+ * Check whether dream consolidation should run.
+ *
+ * Gate order (cheapest first):
+ *   1. Time gate — hours since lastConsolidatedAt >= minHours
+ *   2. Scan throttle — 10-minute interval to suppress redundant scans
+ *   3. Session gate — session count since lastConsolidatedAt >= minSessions
+ *
+ * @returns Session IDs to review, or null if gates failed.
+ */
+export async function shouldTriggerDream(ctx, config = {}) {
+    const cfg = { ...DEFAULT_TRIGGER, ...config };
+    // Read last consolidation timestamp from lock file mtime
+    let lastAt;
+    try {
+        lastAt = await readLastConsolidatedAt(ctx.memoryRoot);
+    }
+    catch {
+        // No lock file = never consolidated = trigger
+        lastAt = 0;
+    }
+    // ── Time gate (required for all trigger paths) ──
+    const hoursSince = (Date.now() - lastAt) / 3_600_000;
+    if (!cfg.force && hoursSince < cfg.minHours)
+        return null;
+    // ── Scan throttle ──
+    const sinceScanMs = Date.now() - lastSessionScanAt;
+    if (!cfg.force && sinceScanMs < cfg.scanIntervalMs)
+        return null;
+    lastSessionScanAt = Date.now();
+    // ── Session gate (with turn-count alternative for single-session users) ──
+    let sessionIds;
+    try {
+        sessionIds = await ctx.listSessionsSince(lastAt);
+    }
+    catch {
+        return null;
+    }
+    // Exclude current session
+    sessionIds = sessionIds.filter(id => id !== ctx.currentSessionId);
+    // Gate: pass if EITHER enough sessions OR enough turns in current session
+    const sessionGatePass = sessionIds.length >= cfg.minSessions;
+    const turnGatePass = (ctx.currentSessionTurnCount ?? 0) >= cfg.minTurnsInSession;
+    if (!cfg.force && !sessionGatePass && !turnGatePass)
+        return null;
+    // If triggered by turn count (single-session user), include current session for review
+    if (!sessionGatePass && turnGatePass) {
+        sessionIds = [ctx.currentSessionId];
+    }
+    return { sessionIds };
+}
+// ── Consolidation Lock (CC consolidationLock parity) ─────────
+async function readLastConsolidatedAt(memoryRoot) {
+    // Gate marker is the source of truth for "last successful consolidation".
+    try {
+        const s = await stat(join(memoryRoot, LAST_CONSOLIDATED_FILE));
+        return s.mtimeMs;
+    }
+    catch {
+        // Legacy fallback: pre-split installs recorded last-consolidated as the lock
+        // mtime. Read it once so the gate doesn't suddenly think it never ran.
+        const s = await stat(join(memoryRoot, LOCK_FILE));
+        return s.mtimeMs;
+    }
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attempt to acquire the consolidation liveness lock.
+ *
+ * A held lock is "live" only if its mtime is fresh (< MAX_DREAM_RUN_MS) AND the
+ * recorded PID is alive. A stale mtime reclaims unconditionally — this defends
+ * against a crashed holder whose PID was reused by an unrelated process (the old
+ * pure-PID check would falsely see it as alive and deadlock for up to an hour).
+ *
+ * @returns 0 on acquisition, or null if blocked by a live holder.
+ */
+export async function tryAcquireConsolidationLock(memoryRoot) {
+    const lockPath = join(memoryRoot, LOCK_FILE);
+    let mtimeMs;
+    let holderPid;
+    try {
+        const [s, raw] = await Promise.all([stat(lockPath), readFile(lockPath, "utf8")]);
+        mtimeMs = s.mtimeMs;
+        const parsed = parseInt(raw.trim(), 10);
+        holderPid = Number.isFinite(parsed) ? parsed : undefined;
+    }
+    catch {
+        // ENOENT — no prior lock, proceed
+    }
+    const fresh = mtimeMs !== undefined && Date.now() - mtimeMs < MAX_DREAM_RUN_MS;
+    if (fresh && holderPid !== undefined && isProcessRunning(holderPid)) {
+        return null; // Blocked by a live, heart-beating holder
+    }
+    await mkdir(memoryRoot, { recursive: true });
+    await writeFile(lockPath, String(process.pid));
+    // Verify we own the lock (race guard)
+    try {
+        const verify = await readFile(lockPath, "utf8");
+        if (parseInt(verify.trim(), 10) !== process.pid)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return 0;
+}
+/**
+ * Refresh the lock mtime so a long-but-legitimate dream is not reclaimed.
+ * Called periodically by the dream runner. No-op if we no longer own the lock.
+ */
+export async function heartbeatConsolidationLock(memoryRoot) {
+    const lockPath = join(memoryRoot, LOCK_FILE);
+    try {
+        const raw = await readFile(lockPath, "utf8");
+        if (parseInt(raw.trim(), 10) !== process.pid)
+            return; // not ours anymore
+        const now = Date.now() / 1000;
+        const { utimes } = await import("node:fs/promises");
+        await utimes(lockPath, now, now);
+    }
+    catch {
+        // Best-effort — a missed heartbeat only risks early reclaim near the ceiling.
+    }
+}
+/** Release the liveness lock explicitly (on failure, abort, or shutdown). */
+export async function releaseConsolidationLock(memoryRoot) {
+    try {
+        await unlink(join(memoryRoot, LOCK_FILE));
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Rollback after a FAILED dream run: release the lock. The gate marker is NOT
+ * touched (only success advances it), so a failed run never delays the next gate.
+ * `_priorMtime` is retained for call-site compatibility and ignored.
+ */
+export async function rollbackConsolidationLock(memoryRoot, _priorMtime) {
+    await releaseConsolidationLock(memoryRoot);
+}
+/**
+ * Record a SUCCESSFUL consolidation: advance the gate marker (mtime = now) and
+ * release the liveness lock.
+ */
+export async function markConsolidationComplete(memoryRoot) {
+    // Advance the gate marker (its mtime = last successful consolidation)...
+    await mkdir(memoryRoot, { recursive: true });
+    await writeFile(join(memoryRoot, LAST_CONSOLIDATED_FILE), String(Date.now()));
+    // ...and release the liveness lock so the next dream can acquire it.
+    await releaseConsolidationLock(memoryRoot);
+}
+// ── Dream Task State Helpers ─────────────────────────────────
+/** Create initial DreamTaskState. */
+export function createDreamTaskState(opts) {
+    return {
+        taskId: `dream-${randomUUID().slice(0, 8)}`,
+        type: "dream",
+        label: "Memory consolidation",
+        permissionRole: "worker",
+        isolation: "shared",
+        lifecycle: "running",
+        depth: 1,
+        maxTurns: 0, // CC parity: dream runs to completion, no turn cap (0 = unlimited)
+        tokenBudget: 0, // Dreams use their own budget
+        startedAt: Date.now(),
+        parentTaskId: opts.parentTaskId,
+        sessionId: opts.sessionId,
+        phase: "starting",
+        sessionsReviewing: opts.sessionsReviewing,
+        filesTouched: [],
+        turns: [],
+        priorLockMtime: opts.priorLockMtime,
+    };
+}
+/** Add a turn to the dream state. */
+export function addDreamTurn(state, turn, touchedPaths) {
+    const seen = new Set(state.filesTouched);
+    const newTouched = touchedPaths.filter(p => !seen.has(p));
+    // Skip no-op updates
+    if (turn.text === "" && turn.toolUseCount === 0 && newTouched.length === 0) {
+        return state;
+    }
+    return {
+        ...state,
+        phase: newTouched.length > 0 ? "updating" : state.phase,
+        filesTouched: newTouched.length > 0
+            ? [...state.filesTouched, ...newTouched]
+            : state.filesTouched,
+        turns: [...state.turns, turn],
+    };
+}
+/** Mark dream as completed. */
+export function completeDreamState(state) {
+    return {
+        ...state,
+        lifecycle: "completed",
+        phase: "completed",
+        endedAt: Date.now(),
+    };
+}
+/** Mark dream as failed. */
+export function failDreamState(state) {
+    return {
+        ...state,
+        lifecycle: "failed",
+        phase: "failed",
+        endedAt: Date.now(),
+    };
+}
+// ── Orchestrator ─────────────────────────────────────────────
+/**
+ * Full dream orchestration entry point.
+ *
+ * This coordinates the entire dream lifecycle:
+ *   1. Check trigger gates
+ *   2. Acquire consolidation lock
+ *   3. Build consolidation prompt
+ *   4. Return dream context for the caller to run through agent loop
+ *
+ * The caller (stdio-server) is responsible for:
+ *   - Running the prompt through the agent's tool loop
+ *   - Applying canUseDreamTool() restrictions via tool.before_invoke hook
+ *   - Calling markConsolidationComplete() on success
+ *   - Calling rollbackConsolidationLock() on failure
+ */
+export async function prepareDreamRun(ctx, config = {}) {
+    const cfg = { ...DEFAULT_TRIGGER, ...config };
+    // ── Gate check ──
+    const gateResult = await shouldTriggerDream(ctx, cfg);
+    if (!gateResult)
+        return null;
+    // ── Acquire lock ──
+    // Both forced (on-demand) and idle dreams acquire the liveness lock — force
+    // bypasses the trigger GATES (handled in shouldTriggerDream), not the lock,
+    // so two dreams never consolidate the same memory concurrently.
+    const acquired = await tryAcquireConsolidationLock(ctx.memoryRoot);
+    if (acquired === null)
+        return null; // Blocked by a live dream
+    const priorMtime = 0;
+    // ── Build prompt ──
+    const prompt = buildConsolidationPrompt(ctx.memoryRoot, ctx.transcriptDir, gateResult.sessionIds);
+    // ── Create task state ──
+    const taskState = createDreamTaskState({
+        sessionId: ctx.currentSessionId,
+        sessionsReviewing: gateResult.sessionIds.length,
+        priorLockMtime: priorMtime,
+    });
+    return {
+        prompt,
+        taskState,
+        sessionIds: gateResult.sessionIds,
+    };
+}
+/**
+ * Run a complete dream consolidation using an isolated forked agent.
+ *
+ * CC parity: This uses runForkedAgent() for true isolation instead of
+ * hook-based tool restriction on the shared agent loop. The dream runs
+ * in its own message history with its own AbortController.
+ *
+ * Full lifecycle:
+ *   1. Check trigger gates
+ *   2. Acquire consolidation lock
+ *   3. Build consolidation prompt
+ *   4. Fork sub-agent with restricted tools
+ *   5. Run to completion
+ *   6. Mark consolidation complete (or rollback on failure)
+ */
+export async function runDream(deps) {
+    const startTime = Date.now();
+    // ── Prepare (gates + lock + prompt) ──
+    const prepared = await prepareDreamRun(deps.context, deps.triggerConfig);
+    if (!prepared) {
+        return {
+            ok: true,
+            sessionsReviewed: 0,
+            filesTouched: [],
+            turns: [],
+            durationMs: Date.now() - startTime,
+        };
+    }
+    const { taskState, sessionIds } = prepared;
+    // Register in the unified task store so dream lifecycle is observable
+    // (task.updated notifications + task tool queries).
+    deps.taskStore?.registerTask(taskState);
+    const settleDreamTask = (ok, output, error) => {
+        deps.taskStore?.updateTask(taskState.taskId, (t) => ({
+            ...t,
+            lifecycle: ok ? "completed" : "failed",
+            phase: ok ? "completed" : "failed",
+            output,
+            error,
+            endedAt: Date.now(),
+        }));
+    };
+    // P5: Scan category manifest for category-aware merge rules
+    let categoryContext = "";
+    try {
+        const manifest = await scanCategoryManifest(deps.context.memoryRoot);
+        if (manifest.totalFiles > 0) {
+            categoryContext = formatCategoryContextBlock(manifest);
+        }
+    }
+    catch {
+        // Non-fatal: dream proceeds without category context
+    }
+    // Rebuild prompt with memory awareness + category context + temporal context
+    const hasMemory = !!(deps.memoryProvider && deps.memoryUserId);
+    // ── Temporal context: inject recent activity summary into Dream ──
+    let temporalContext = "";
+    if (hasMemory && deps.memoryProvider?.getActivitySummary) {
+        try {
+            const summary = deps.memoryProvider.getActivitySummary(deps.memoryUserId, 7);
+            if (summary.dailyCounts.length > 0) {
+                const lines = ["## Recent Memory Activity (last 7 days)"];
+                lines.push("");
+                for (const day of summary.dailyCounts) {
+                    lines.push(`- ${day.date}: ${day.count} memories recorded`);
+                }
+                if (summary.highlights.length > 0) {
+                    lines.push("");
+                    lines.push("**High-importance entries:**");
+                    for (const h of summary.highlights.slice(0, 10)) {
+                        lines.push(`- [${h.category}] ${h.text.slice(0, 100)}${h.text.length > 100 ? "..." : ""} (${h.date})`);
+                    }
+                }
+                temporalContext = "\n" + lines.join("\n") + "\n";
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    // ── User Profile context: inject known preferences for continuity ──
+    let profileContext = "";
+    if (hasMemory && deps.memoryProvider?.getAllProfiles) {
+        try {
+            const profiles = deps.memoryProvider.getAllProfiles(deps.memoryUserId);
+            const entries = Object.entries(profiles);
+            if (entries.length > 0) {
+                const lines = ["## Known User Profile"];
+                lines.push("");
+                for (const [key, value] of entries.slice(0, 20)) {
+                    lines.push(`- **${key}**: ${value}`);
+                }
+                profileContext = "\n" + lines.join("\n") + "\n";
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    let sessionDigest = "";
+    try {
+        sessionDigest = await readSessionDigest(deps.context.transcriptDir, sessionIds);
+    }
+    catch {
+        sessionDigest = "";
+    }
+    const prompt = buildConsolidationPrompt(deps.context.memoryRoot, deps.context.transcriptDir, sessionIds, {
+        hasQMemory: hasMemory,
+        categoryContext: categoryContext || undefined,
+        temporalContext: temporalContext || undefined,
+        profileContext: profileContext || undefined,
+        sessionDigest: sessionDigest || undefined,
+    });
+    deps.log.info(`[dream] starting consolidation — ${sessionIds.length} sessions, ` +
+        `memoryRoot=${deps.context.memoryRoot}` +
+        (hasMemory ? ", memory=enabled" : ""));
+    // Fire subagent.started hook
+    deps.hooks?.invoke("subagent.started", {
+        sessionId: deps.context.currentSessionId,
+        turnId: taskState.taskId,
+        subagentId: taskState.taskId,
+        agentType: "dream",
+    }).catch(() => { });
+    // ── Build tool restriction function ──
+    const canUse = (toolName, input) => canUseDreamTool(deps.context.memoryRoot, { toolName, input });
+    // ── Memory virtual tools (injected when provider present) ──
+    const qmemoryToolDefs = hasMemory ? [
+        {
+            type: "function",
+            function: {
+                name: "qmemory_search",
+                description: "Search the user's long-term memory (QMemory). Returns relevant memories sorted by relevance.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "Semantic search query" },
+                        limit: { type: "number", description: "Max results (default: 10)" },
+                    },
+                    required: ["query"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "qmemory_store",
+                description: "Submit a low-priority candidate to the memory consolidation pipeline. Use for user preferences, facts, and cross-project knowledge; it may merge, conflict, or wait for confirmation.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "The candidate memory text to submit" },
+                        source: { type: "string", description: "Source label (e.g. 'dream-consolidation')" },
+                    },
+                    required: ["text"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "qmemory_feedback",
+                description: "Submit feedback on recalled memories (e.g. mark as outdated or wrong).",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        memoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories to give feedback on" },
+                        signal: { type: "string", enum: ["useful", "irrelevant", "outdated", "wrong"], description: "Feedback signal" },
+                    },
+                    required: ["memoryIds", "signal"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "qmemory_temporal",
+                description: "Query memories by time range. Use for temporal synthesis ('what happened last week', 'recent decisions').",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        days: { type: "number", description: "Look back N days from today (default: 7)" },
+                        category: { type: "string", description: "Filter by category (optional)" },
+                    },
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "qmemory_profile",
+                description: "Read or write user profile entries. Use 'get' to read all, 'set' to update a key.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        action: { type: "string", enum: ["get", "set"], description: "Action to perform" },
+                        key: { type: "string", description: "Profile key (required for 'set')" },
+                        value: { type: "string", description: "Profile value (required for 'set')" },
+                    },
+                    required: ["action"],
+                },
+            },
+        },
+    ] : [];
+    // ── Wrap tool invoker to handle memory tool calls ──
+    const wrappedToolInvoker = hasMemory
+        ? {
+            invoke: async (turnId, name, args, signal) => {
+                const provider = deps.memoryProvider;
+                const userId = deps.memoryUserId;
+                if (name === "qmemory_search") {
+                    const { query, limit } = JSON.parse(args);
+                    const results = await provider.search(query, userId, { limit: limit ?? 10 });
+                    return { result: JSON.stringify(results) };
+                }
+                if (name === "qmemory_store") {
+                    if (!provider.proposeExtracted)
+                        return { result: "", error: "memory proposals are not supported" };
+                    const { text, source } = JSON.parse(args);
+                    const result = await provider.proposeExtracted([{ text, category: "insight", importance: 0.45 }], userId, {
+                        sessionId: deps.context.currentSessionId,
+                        source: source ?? "dream-consolidation",
+                    });
+                    return { result: JSON.stringify(result) };
+                }
+                if (name === "qmemory_feedback") {
+                    if (!provider.feedback)
+                        return { result: "Feedback noted (no handler)." };
+                    const { memoryIds, signal } = JSON.parse(args);
+                    const result = await provider.feedback(memoryIds, signal);
+                    return { result: `Feedback applied to ${result.affected} memories.` };
+                }
+                if (name === "qmemory_temporal") {
+                    if (!provider.synthesizeTimeline)
+                        return { result: "Temporal synthesis not available." };
+                    const { days, category } = JSON.parse(args);
+                    const lookbackDays = days ?? 7;
+                    const startMs = Date.now() - lookbackDays * 86_400_000;
+                    const timeline = provider.synthesizeTimeline(userId, startMs, Date.now());
+                    return { result: timeline };
+                }
+                if (name === "qmemory_profile") {
+                    const { action, key, value } = JSON.parse(args);
+                    if (action === "get") {
+                        if (!provider.getAllProfiles)
+                            return { result: "{}" };
+                        const profiles = provider.getAllProfiles(userId);
+                        return { result: JSON.stringify(profiles) };
+                    }
+                    if (action === "set" && key && value) {
+                        if (!provider.setProfile)
+                            return { result: "Profile write not available." };
+                        provider.setProfile(userId, key, value);
+                        return { result: `Profile updated: ${key} = ${value}` };
+                    }
+                    return { result: "Invalid profile action. Use 'get' or 'set' with key/value." };
+                }
+                return deps.toolInvoker.invoke(turnId, name, args, signal);
+            },
+        }
+        : deps.toolInvoker;
+    // Filter tools to only those allowed by canUseDreamTool.
+    // This dramatically reduces token count — the full manifest has dozens of
+    // tools (video, image, tts, team, cron...) irrelevant to dream.
+    const DREAM_ALLOWED_TOOLS = new Set([
+        "read", "write", "edit", "patch", "exec", "search",
+        "qmemory_search", "qmemory_store", "qmemory_feedback", "qmemory_temporal", "qmemory_profile",
+    ]);
+    const filteredTools = deps.tools.filter((t) => DREAM_ALLOWED_TOOLS.has(t.function.name));
+    const allTools = [...filteredTools, ...qmemoryToolDefs];
+    // Heartbeat the liveness lock while the dream runs so a legitimately long
+    // consolidation isn't reclaimed at the MAX_DREAM_RUN_MS ceiling.
+    const heartbeat = setInterval(() => {
+        void heartbeatConsolidationLock(deps.context.memoryRoot);
+    }, LOCK_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    try {
+        // ── Run forked agent ──
+        const result = await runForkedAgent({
+            promptMessages: [
+                { role: "user", content: "Begin memory consolidation." },
+            ],
+            systemPrompt: prompt,
+            tools: allTools,
+            canUseTool: canUse,
+            transport: deps.transport,
+            toolInvoker: wrappedToolInvoker,
+            createAgentRunner: deps.createAgentRunner,
+            apiKey: deps.apiKey,
+            model: deps.model,
+            log: deps.log,
+            // Do NOT pass parent hooks — the parent's PermissionChecker hook would
+            // send tool.approval.request notifications that no host can respond to
+            // (dream runs autonomously). Security is enforced by canUseDreamTool.
+            hooks: undefined,
+            forkLabel: "dream-consolidation",
+            // Safety cap: dream typically completes in <10 rounds. Cap at 15 to
+            // prevent runaway loops with slower models while still allowing
+            // thorough consolidation.
+            maxTurns: 15,
+            parentSignal: deps.parentSignal,
+            skipTranscript: true,
+        });
+        // ── Extract touched files from events ──
+        const filesTouched = [];
+        for (const event of result.events) {
+            if (event.type === "tool_call") {
+                try {
+                    const args = JSON.parse(event.arguments);
+                    const path = (args.file_path ?? args.path ?? args.filePath);
+                    if (path && isWithinMemoryDir(path, deps.context.memoryRoot)) {
+                        filesTouched.push(path);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+        }
+        // ── Mark complete or rollback ──
+        if (result.ok) {
+            const summaryPath = await persistDreamSummaryArtifact({
+                memoryRoot: deps.context.memoryRoot,
+                sessionsReviewed: sessionIds.length,
+                durationMs: result.durationMs,
+                events: result.events,
+                filesTouched,
+                sessionDigest: sessionDigest || undefined,
+            });
+            filesTouched.push(summaryPath);
+            await markConsolidationComplete(deps.context.memoryRoot);
+            deps.log.info(`[dream] consolidation complete — ${filesTouched.length} files touched, ` +
+                `${result.durationMs}ms`);
+        }
+        else {
+            await rollbackConsolidationLock(deps.context.memoryRoot, taskState.priorLockMtime);
+            deps.log.warn(`[dream] consolidation failed: ${result.error}`);
+        }
+        // Fire subagent.stopped hook
+        deps.hooks?.invoke("subagent.stopped", {
+            sessionId: deps.context.currentSessionId,
+            turnId: taskState.taskId,
+            subagentId: taskState.taskId,
+            agentType: "dream",
+            reason: result.ok ? "normal" : "error",
+            error: result.error,
+        }).catch(() => { });
+        const uniqueFiles = [...new Set(filesTouched)];
+        settleDreamTask(result.ok, `Reviewed ${sessionIds.length} sessions, touched ${uniqueFiles.length} memory files.`, result.error);
+        return {
+            ok: result.ok,
+            sessionsReviewed: sessionIds.length,
+            filesTouched: uniqueFiles,
+            turns: [], // Turns are tracked internally by the forked agent
+            durationMs: Date.now() - startTime,
+            error: result.error,
+        };
+    }
+    catch (err) {
+        // Rollback lock on crash
+        await rollbackConsolidationLock(deps.context.memoryRoot, taskState.priorLockMtime).catch(() => { });
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        deps.log.warn(`[dream] consolidation error: ${errorMsg}`);
+        deps.hooks?.invoke("subagent.stopped", {
+            sessionId: deps.context.currentSessionId,
+            turnId: taskState.taskId,
+            subagentId: taskState.taskId,
+            agentType: "dream",
+            reason: "error",
+            error: errorMsg,
+        }).catch(() => { });
+        settleDreamTask(false, "", errorMsg);
+        return {
+            ok: false,
+            sessionsReviewed: 0,
+            filesTouched: [],
+            turns: [],
+            durationMs: Date.now() - startTime,
+            error: errorMsg,
+        };
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+}