dreamer + git-commits: three UX fixes from live triage

1. Git-commit sweeps park structurally non-indexable directories (not a
   git repo, or a repo with no commits) on a 24h re-probe cooldown
   instead of retrying and logging the full git error every 15-minute
   tick. Two such projects were flooding a user's recent-errors log,
   drowning real errors in doctor reports. A plain directory that gets
   git-init'ed (or an empty repo that gains its first commit) is picked
   up at the next re-probe.

2. Manual /ctx-dream runs wait up to 60s for a busy domain lease. The
   lease holder is usually a scheduled catch-up task on the same domain
   finishing within seconds; giving up instantly turned an explicit user
   command into a confusing 'busy, try again'. Scheduled ticks still
   never wait.

3. The busy message no longer claims the requested task is 'already
   running': the domain lease is usually held by a SIBLING task (a
   scheduled verify blocking a manual curate). Both harnesses now say
   another dream task holds the domain's lease and suggest retrying.

Author: ualtinok

packages/pi-plugin/src/commands/ctx-dream.ts

@@ -103,7 +103,10 @@ export function registerCtxDreamCommand(
 					lines.push(`Skipped (no work): ${result.skippedNoWork.join(", ")}`);
 				if (result.deferredBusy.length > 0)
 					lines.push(
-						`Busy (already running): ${result.deferredBusy.join(", ")}`,
+						// "Busy" means the task's DOMAIN lease is held — usually
+						// a sibling task (e.g. a scheduled verify blocking a
+						// manual curate), not this task itself.
+						`Busy: ${result.deferredBusy.join(", ")} — another dream task holds this domain's lease; retry in a minute`,
 					);
 				if (lines.length === 0) lines.push("No enabled dream tasks to run.");
 

packages/pi-plugin/src/pi-todo-inject.test.ts

@@ -174,10 +174,7 @@ describe("injectSyntheticTodowriteForPi", () => {
 
 			// Defer pass: the pair must NOT attach to the aborted anchor (skip
 			// silently, same as an anchor outside the visible window).
-			const deferMessages = [
-				aborted,
-				good,
-			] as unknown as Parameters<
+			const deferMessages = [aborted, good] as unknown as Parameters<
 				typeof injectSyntheticTodowriteForPi
 			>[0]["messages"];
 			injectSyntheticTodowriteForPi({
@@ -200,11 +197,7 @@ describe("injectSyntheticTodowriteForPi", () => {
 				stopReason: "error",
 				timestamp: 3,
 			};
-			const bustMessages = [
-				aborted,
-				good,
-				errored,
-			] as unknown as Parameters<
+			const bustMessages = [aborted, good, errored] as unknown as Parameters<
 				typeof injectSyntheticTodowriteForPi
 			>[0]["messages"];
 			injectSyntheticTodowriteForPi({
@@ -218,8 +211,7 @@ describe("injectSyntheticTodowriteForPi", () => {
 			expect(findOrphanedFunctionCallOutputs(bustMessages)).toEqual([]);
 			const anchor = getPersistedTodoSyntheticAnchor(db, sessionId);
 			expect(anchor?.messageId).toBe("resp_good");
-			const goodContent = (good as { content: Array<{ id?: string }> })
-				.content;
+			const goodContent = (good as { content: Array<{ id?: string }> }).content;
 			expect(goodContent.some((b) => b.id === callId)).toBe(true);
 		} finally {
 			closeQuietly(db);

packages/plugin/src/features/magic-context/dreamer/task-scheduler.test.ts

@@ -56,6 +56,69 @@ function seedActiveMemory(d: Database, project = PROJECT): void {
     });
 }
 
+describe("task-scheduler — manual lease wait", () => {
+    it("manual run waits for a briefly-held domain lease instead of reporting busy", async () => {
+        db = freshDb();
+        seedActiveMemory(db);
+        const leaseKey = leaseKeyFor("curate", PROJECT);
+        const otherHolder = "other-process";
+        expect(acquireLease(db, otherHolder, leaseKey)).toBe(true);
+        // Free the lease shortly after the manual run starts waiting.
+        setTimeout(() => releaseLease(db as Database, otherHolder, leaseKey), 150);
+
+        let executed = 0;
+        const executor = async (): Promise<TaskExecOutcome> => {
+            executed += 1;
+            return { status: "completed" };
+        };
+        const result = await runManualDream({
+            db,
+            projectIdentity: PROJECT,
+            tasks: [cfg("curate", "0 4 * * 0")],
+            executor,
+            task: "curate",
+        });
+        expect(executed).toBe(1);
+        expect(result.ran).toEqual(["curate"]);
+        expect(result.deferredBusy).toEqual([]);
+    });
+
+    it("scheduled ticks do not wait on a busy lease", async () => {
+        db = freshDb();
+        seedActiveMemory(db);
+        const leaseKey = leaseKeyFor("curate", PROJECT);
+        expect(acquireLease(db, "other-process", leaseKey)).toBe(true);
+
+        const now = Date.now();
+        writeTaskScheduleState(db, {
+            projectPath: PROJECT,
+            task: "curate",
+            lastRunAt: null,
+            nextDueAt: now - 1000,
+            schedule: "0 4 * * 0",
+            lastStatus: null,
+            lastError: null,
+            retryCount: 0,
+        });
+        let executed = 0;
+        const executor = async (): Promise<TaskExecOutcome> => {
+            executed += 1;
+            return { status: "completed" };
+        };
+        const started = Date.now();
+        await runDueTasksForProject({
+            db,
+            projectIdentity: PROJECT,
+            tasks: [cfg("curate", "0 4 * * 0")],
+            executor,
+            now,
+        });
+        expect(executed).toBe(0);
+        // No lease-wait loop on the scheduled path: returns immediately.
+        expect(Date.now() - started).toBeLessThan(1500);
+    });
+});
+
 describe("task-scheduler — planDueTasks", () => {
     it("first-seed does NOT fire immediately (next_due in the future)", () => {
         db = freshDb();

packages/plugin/src/features/magic-context/dreamer/task-scheduler.ts

@@ -256,11 +256,21 @@ function recordTransientFailure(
 interface DomainGroupCallbacks {
     /** Manual single-task run ignores the post-lease activity gate re-check. */
     forceGate?: boolean;
+    /**
+     * How long a manual run may wait for a busy domain lease before giving
+     * up. Scheduled ticks leave this unset (the next tick retries anyway).
+     */
+    leaseWaitMs?: number;
     onRan?: (task: DreamTaskName) => void;
     onFailed?: (task: DreamTaskName) => void;
     onBusy?: (task: DreamTaskName) => void;
 }
 
+/** Poll cadence while a manual run waits for a busy domain lease. */
+const LEASE_WAIT_POLL_MS = 2_000;
+/** Lease wait budget for manual /ctx-dream runs. */
+export const MANUAL_RUN_LEASE_WAIT_MS = 60_000;
+
 async function runDomainGroup(
     deps: RunDueTasksDeps,
     group: DueTask[],
@@ -271,7 +281,20 @@ async function runDomainGroup(
     const leaseKey = leaseKeyFor(group[0].config.task, projectIdentity);
     const holderId = crypto.randomUUID();
 
-    if (!acquireLease(db, holderId, leaseKey)) {
+    let acquired = acquireLease(db, holderId, leaseKey);
+    if (!acquired && cb?.leaseWaitMs) {
+        // Explicit manual run: the lease holder is usually a scheduled
+        // catch-up task on the same domain finishing within seconds. Waiting
+        // briefly turns a confusing "busy, try again" into the run the user
+        // asked for. Scheduled ticks never wait (leaseWaitMs unset) — the next
+        // tick retries anyway.
+        const deadline = Date.now() + cb.leaseWaitMs;
+        while (!acquired && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, LEASE_WAIT_POLL_MS));
+            acquired = acquireLease(db, holderId, leaseKey);
+        }
+    }
+    if (!acquired) {
         // Busy (a long sibling run or another process holds it). Leave next_due_at
         // unchanged so these tasks re-attempt next tick — they run the instant the
         // lease frees. No state write.
@@ -430,6 +453,7 @@ export async function runManualDream(
         [...groups.values()].map((group) =>
             runDomainGroup({ ...deps, executor: deps.executor }, group, {
                 forceGate,
+                leaseWaitMs: MANUAL_RUN_LEASE_WAIT_MS,
                 onRan: (t) => result.ran.push(t),
                 onFailed: (t) => result.failed.push(t),
                 onBusy: (t) => result.deferredBusy.push(t),

packages/plugin/src/features/magic-context/git-commits/git-log-reader.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { parseGitLogOutput, readGitCommits } from "./git-log-reader";
+import { classifyGitLogFailure, parseGitLogOutput, readGitCommits } from "./git-log-reader";
 
 // Field separator is US (0x1f, ASCII Unit Separator). We deliberately moved
 // off NUL (0x00) because Node's child_process.execFile rejects argv elements
@@ -75,3 +75,28 @@ describe("readGitCommits (smoke)", () => {
         expect(Array.isArray(commits)).toBe(true);
     });
 });
+
+describe("classifyGitLogFailure", () => {
+    it("classifies structural failures that cannot succeed on retry", () => {
+        expect(
+            classifyGitLogFailure(
+                "Command failed: git log HEAD\nfatal: not a git repository (or any of the parent directories): .git",
+            ),
+        ).toBe("not_a_repo");
+        expect(
+            classifyGitLogFailure(
+                "Command failed: git log HEAD\nfatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.",
+            ),
+        ).toBe("no_head");
+        expect(
+            classifyGitLogFailure(
+                "fatal: your current branch 'main' does not have any commits yet",
+            ),
+        ).toBe("no_head");
+    });
+
+    it("keeps everything else transient so normal retries continue", () => {
+        expect(classifyGitLogFailure("spawn git ENOENT")).toBe("transient");
+        expect(classifyGitLogFailure("Command failed: git log HEAD (timeout)")).toBe("transient");
+    });
+});

packages/plugin/src/features/magic-context/git-commits/git-log-reader.ts

@@ -39,6 +39,28 @@ const DEFAULT_MAX_COMMITS = 5000;
 const RECORD_SEPARATOR = "\x1e";
 const FIELD_SEPARATOR = "\x1f";
 
+/**
+ * Why `git log` produced no commits, when it failed. `not_a_repo` and
+ * `no_head` (a repo with zero commits) are structural: retrying every sweep
+ * tick cannot succeed and only floods the log, so callers put the project on
+ * a long re-probe cooldown instead. `transient` covers everything else
+ * (timeouts, missing git binary, permission errors) and keeps the normal
+ * retry cadence.
+ */
+export type GitLogFailureKind = "not_a_repo" | "no_head" | "transient";
+
+export function classifyGitLogFailure(message: string): GitLogFailureKind {
+    if (message.includes("not a git repository")) return "not_a_repo";
+    if (
+        message.includes("unknown revision or path not in the working tree") ||
+        message.includes("does not have any commits yet") ||
+        message.includes("bad revision")
+    ) {
+        return "no_head";
+    }
+    return "transient";
+}
+
 export interface GitCommit {
     /** Full 40-char SHA. */
     sha: string;
@@ -80,6 +102,19 @@ export async function readGitCommits(
     directory: string,
     options: ReadGitCommitsOptions = {},
 ): Promise<GitCommit[]> {
+    return (await readGitCommitsResult(directory, options)).commits;
+}
+
+/**
+ * Like {@link readGitCommits}, but also reports WHY the read failed so the
+ * sweep can distinguish structurally non-indexable directories (not a repo,
+ * repo with no commits) from transient errors. `failure` is null on success —
+ * including a successful read that matched zero commits.
+ */
+export async function readGitCommitsResult(
+    directory: string,
+    options: ReadGitCommitsOptions = {},
+): Promise<{ commits: GitCommit[]; failure: GitLogFailureKind | null }> {
     // Guard against argument injection: a `branch` value beginning with `-`
     // would be parsed as a git OPTION (not a revision) since it sits ahead of
     // the format/since flags below. No shell is involved (execFile), so this
@@ -124,12 +159,23 @@ export async function readGitCommits(
     } catch (error) {
         // Intentional: git may not be installed, directory may not be a repo,
         // or the invocation may time out. All are "skip indexing this cycle"
-        // conditions, not crashes. We return empty and the next sweep will
-        // retry. We DO log the reason though — a silent empty-result masked a
-        // real cwd / PATH / timeout bug during the v0.14 git-commits rollout.
+        // conditions, not crashes. We return empty; transient failures retry
+        // next sweep, structural ones (classified below) go on a long cooldown.
+        // We DO log the reason though — a silent empty-result masked a real
+        // cwd / PATH / timeout bug during the v0.14 git-commits rollout.
         const message = error instanceof Error ? error.message : String(error);
-        log(`[git-commits] readGitCommits failed for ${projectLabel}: ${message.slice(0, 500)}`);
-        return [];
+        const failure = classifyGitLogFailure(message);
+        if (failure === "transient") {
+            log(
+                `[git-commits] readGitCommits failed for ${projectLabel}: ${message.slice(0, 500)}`,
+            );
+        } else {
+            // One quiet line instead of the full multi-line git error: these
+            // directories fail the same way every sweep and were flooding the
+            // recent-errors section of doctor reports.
+            log(`[git-commits] ${projectLabel} is not indexable (${failure})`);
+        }
+        return { commits: [], failure };
     }
 
     if (stdout.trim().length === 0) {
@@ -138,7 +184,7 @@ export async function readGitCommits(
         );
     }
 
-    return parseGitLogOutput(stdout);
+    return { commits: parseGitLogOutput(stdout), failure: null };
 }
 
 export function parseGitLogOutput(stdout: string): GitCommit[] {

packages/plugin/src/features/magic-context/git-commits/index.ts

@@ -38,6 +38,7 @@ export {
     type GitSweepLeaseResult,
     getGitSweepCoordinatorState,
     markGitSweepSuccessAndRelease,
+    parkGitSweepNonIndexable,
     releaseGitSweepLease,
     renewGitSweepLease,
 } from "./sweep-coordinator";

packages/plugin/src/features/magic-context/git-commits/indexer.ts

@@ -13,7 +13,7 @@
 import { log } from "../../../shared/logger";
 import type { Database } from "../../../shared/sqlite";
 import { embedBatchForProject, getProjectEmbeddingSnapshot } from "../memory/embedding";
-import { readGitCommits } from "./git-log-reader";
+import { readGitCommits, readGitCommitsResult } from "./git-log-reader";
 import {
     countEmbeddedCommits,
     loadUnembeddedCommits,
@@ -49,6 +49,12 @@ export interface IndexCommitsResult {
     updated: number;
     evicted: number;
     embedded: number;
+    /**
+     * Set when `git log` failed structurally (directory is not a repo, or the
+     * repo has no commits yet). The sweep uses this to park the project on a
+     * long re-probe cooldown instead of retrying every tick.
+     */
+    nonIndexable: boolean;
 }
 
 /**
@@ -70,6 +76,7 @@ export async function indexCommitsForProject(
         updated: 0,
         evicted: 0,
         embedded: 0,
+        nonIndexable: false,
     };
 
     if (indexInProgress.has(projectPath)) {
@@ -88,13 +95,19 @@ export async function indexCommitsForProject(
                   Math.max(latestIndexed - 60_000, Date.now() - options.sinceDays * MS_PER_DAY)
                 : Date.now() - options.sinceDays * MS_PER_DAY;
 
-        const commits = await readGitCommits(directory, {
+        const read = await readGitCommitsResult(directory, {
             sinceMs,
             maxCommits: options.maxCommits,
             projectIdentity: projectPath,
         });
+        const commits = read.commits;
         result.scanned = commits.length;
 
+        if (read.failure === "not_a_repo" || read.failure === "no_head") {
+            result.nonIndexable = true;
+            return result;
+        }
+
         if (commits.length === 0) {
             // No new commits. Still enforce the cap in case prior runs overflowed.
             result.evicted = enforceProjectCap(db, projectPath, options.maxCommits);

packages/plugin/src/features/magic-context/git-commits/sweep-coordinator.test.ts

@@ -9,6 +9,7 @@ import {
     GIT_SWEEP_COOLDOWN_MS,
     getGitSweepCoordinatorState,
     markGitSweepSuccessAndRelease,
+    parkGitSweepNonIndexable,
     releaseGitSweepLease,
 } from "./sweep-coordinator";
 
@@ -155,4 +156,28 @@ describe("git sweep coordinator", () => {
         expect(retry.acquired).toBe(true);
         expect(getGitSweepCoordinatorState(db, projectPath)?.leaseHolder).toBe("holder-b");
     });
+
+    it("parks a non-indexable project on the long re-probe cooldown", () => {
+        const PROJECT = "dir:non-indexable";
+        const holder = "holder-park";
+        const first = acquireGitSweepLease(db, PROJECT, holder);
+        expect(first.acquired).toBe(true);
+
+        expect(parkGitSweepNonIndexable(db, PROJECT, holder)).toBe(true);
+
+        // Immediately after parking: cooldown blocks, far in the future.
+        const blocked = acquireGitSweepLease(db, PROJECT, "holder-2");
+        expect(blocked.acquired).toBe(false);
+        if (!blocked.acquired) {
+            expect(blocked.reason).toBe("cooldown_active");
+            // Re-probe horizon is ~24h out, well past the ordinary 10m cooldown.
+            expect((blocked.nextAllowedAt ?? 0) - Date.now()).toBeGreaterThan(60 * 60 * 1000);
+        }
+
+        // A short custom horizon expires and allows the re-probe.
+        const holder3 = "holder-3";
+        const again = acquireGitSweepLease(db, PROJECT, holder3);
+        expect(again.acquired).toBe(false);
+        expect(parkGitSweepNonIndexable(db, PROJECT, holder3, 1)).toBe(false);
+    });
 });