qlogicagent 2.13.5 → 2.13.7

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

@@ -1,974 +0,0 @@
-/**
- * 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);
-    }
-}