Function runDream

bin/gstack-gbrain-sync.ts:1200–1358

(args: CliArgs)

 * optional maintenance.
 */
export async function runDream(args: CliArgs): Promise<StageResult> {
  const t0 = Date.now();

  if (args.mode === "dry-run") {
    const root = repoRoot();
    const sourceId = root ? deriveCodeSourceId(root) : null;
    return {
      name: "dream",
      ran: false,
      ok: true,
      duration_ms: 0,
      summary: sourceId
        ? `would: gbrain dream --source ${sourceId}  (build this source's call graph)`
        : "would: gbrain dream  (call-graph build)",
    };
  }

  const localStatus = localEngineStatus({ noCache: false });
  if (localStatus === "timeout") {
    warnProbeTimeout("dream"); // #1964: slow-but-healthy — proceed
  } else if (localStatus !== "ok") {
    return skipStageForLocalStatus("dream", localStatus, t0);
  }

  // Dedupe concurrent dreams across worktrees (lock-free path).
  if (!acquireDreamMarker()) {
    const pid = dreamMarkerPid();
    return {
      name: "dream",
      ran: false,
      ok: true,
      duration_ms: Date.now() - t0,
      summary: `dream already running${pid !== null ? ` (pid ${pid})` : ""} — skipped`,
    };
  }

  try {
    const dreamTimeoutMs = resolveStageTimeoutMs(
      process.env.GSTACK_SYNC_DREAM_TIMEOUT_MS,
      "GSTACK_SYNC_DREAM_TIMEOUT_MS",
      DEFAULT_DREAM_TIMEOUT_MS,
    );

    // Scope the cycle to THIS worktree's code source: `gbrain dream --source <id>`.
    // Verified empirically (not just from `gbrain --help`): plain `gbrain dream`
    // cycles the brain's default source and never runs the source-scoped `extract`
    // phase for our code source, so the call graph for the pinned source stays
    // empty. `gbrain dream --source <id>` runs the per-source cycle (the form
    // `gbrain doctor` recommends for stale sources) and is what actually populates
    // code-callers/code-callees for this worktree. Falls back to plain `dream`
    // only when we can't derive the source id (not in a git repo).
    const root = repoRoot();
    const sourceId = root ? deriveCodeSourceId(root) : null;
    const dreamArgs = sourceId ? ["dream", "--source", sourceId] : ["dream"];

    // spawnGbrain seeds DATABASE_URL from gbrain's config via buildGbrainEnv.
    //
    // We CAPTURE output (pipe) rather than inherit because `gbrain dream` exits 0