trekoon 0.3.0 → 0.3.2

package/src/commands/session.ts

@@ -1,17 +1,13 @@
-import type { Database } from "bun:sqlite";
-
+import { parseArgs, readOption } from "./arg-parser";
 import { unexpectedFailureResult } from "./error-utils";
+import { DEFAULT_SOURCE_BRANCH, resolveSyncStatus } from "./sync-helpers";
 import { buildTaskReadiness, type DependencyBlocker } from "./task-readiness";
 
 import { TrackerDomain } from "../domain/tracker-domain";
 import { okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
-import { countBranchEventsSince } from "../sync/branch-db";
-import { persistGitContext, resolveGitContext } from "../sync/git-context";
-import { type GitContextSnapshot, type SyncStatusSummary } from "../sync/types";
-
-const DEFAULT_SOURCE_BRANCH = "main";
+import { type GitContextSnapshot } from "../sync/types";
 
 interface SessionReadiness {
   readonly readyCount: number;
@@ -50,73 +46,6 @@ interface SessionResult {
   readonly readiness: SessionReadiness;
 }
 
-function countAheadLocal(db: Database, currentBranch: string | null, sourceBranch: string): number {
-  if (!currentBranch || currentBranch === sourceBranch) {
-    return 0;
-  }
-
-  const row = db
-    .query(
-      `
-      SELECT COUNT(*) AS count
-      FROM events
-      WHERE git_branch = @branch;
-      `,
-    )
-    .get({ "@branch": currentBranch }) as { count: number } | null;
-
-  return row?.count ?? 0;
-}
-
-function countPendingConflictsLocal(db: Database): number {
-  const row = db
-    .query("SELECT COUNT(*) AS count FROM sync_conflicts WHERE resolution = 'pending';")
-    .get() as { count: number } | null;
-
-  return row?.count ?? 0;
-}
-
-function loadCursorLocal(
-  db: Database,
-  worktreePath: string,
-  sourceBranch: string,
-): { cursor_token: string } | null {
-  return db
-    .query(
-      `
-      SELECT cursor_token
-      FROM sync_cursors
-      WHERE owner_scope = 'worktree'
-        AND owner_worktree_path = ?
-        AND source_branch = ?
-      LIMIT 1;
-      `,
-    )
-    .get(worktreePath, sourceBranch) as { cursor_token: string } | null;
-}
-
-function resolveSyncStatus(
-  database: TrekoonDatabase,
-  cwd: string,
-  sourceBranch: string,
-): SyncStatusSummary {
-  const git: GitContextSnapshot = resolveGitContext(cwd);
-  persistGitContext(database.db, git);
-
-  const cursor = loadCursorLocal(database.db, git.worktreePath, sourceBranch);
-  const cursorToken: string = cursor?.cursor_token ?? "0:";
-  const onSourceBranch: boolean = git.branchName !== null && git.branchName === sourceBranch;
-
-  return {
-    sourceBranch,
-    ahead: countAheadLocal(database.db, git.branchName, sourceBranch),
-    behind: onSourceBranch ? 0 : countBranchEventsSince(database.db, sourceBranch, cursorToken),
-    pendingConflicts: countPendingConflictsLocal(database.db),
-    sameBranch: onSourceBranch,
-    git,
-  };
-}
-
 
 function formatSessionHuman(result: SessionResult): string {
   const lines: string[] = [];
@@ -173,12 +102,15 @@ export async function runSession(context: CliContext): Promise<CliResult> {
   let database: TrekoonDatabase | undefined;
 
   try {
+    const parsed = parseArgs(context.args);
+    const epicId: string | undefined = readOption(parsed.options, "epic");
+
     database = openTrekoonDatabase(context.cwd);
     const diagnostics = database.diagnostics;
 
     const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
     const domain = new TrackerDomain(database.db);
-    const readiness = buildTaskReadiness(domain, undefined);
+    const readiness = buildTaskReadiness(domain, epicId);
     const topCandidate = readiness.candidates[0] ?? null;
 
     let nextTask: NextCandidate | null = null;

package/src/commands/skills.ts

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -79,6 +79,10 @@ function resolveBundledSkillFilePath(): string {
   return fileURLToPath(new URL("../../.agents/skills/trekoon/SKILL.md", import.meta.url));
 }
 
+function resolveBundledSkillDirPath(): string {
+  return fileURLToPath(new URL("../../.agents/skills/trekoon", import.meta.url));
+}
+
 function toAbsolutePath(cwd: string, pathValue: string): string {
   if (isAbsolute(pathValue)) {
     return pathValue;
@@ -234,6 +238,7 @@ function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
 
 function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; installedPath: string; installedDir: string } {
   const sourcePath: string = resolveBundledSkillFilePath();
+  const sourceDir: string = resolveBundledSkillDirPath();
   if (!existsSync(sourcePath)) {
     return failResult({
       command: "skills.install",
@@ -255,6 +260,12 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
   try {
     mkdirSync(installedDir, { recursive: true });
     copyFileSync(sourcePath, installedPath);
+    // Copy reference guides if they exist in the bundled source.
+    const sourceRefDir: string = join(sourceDir, "reference");
+    if (existsSync(sourceRefDir)) {
+      const installedRefDir: string = join(installedDir, "reference");
+      cpSync(sourceRefDir, installedRefDir, { recursive: true });
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -298,39 +309,28 @@ function replaceOrCreateSymlink(
 
   const existing = lstatSync(linkPath);
   if (!existing.isSymbolicLink()) {
-    return failResult({
-      command: "skills.install",
-      human: `Cannot create symlink: path exists and is not a link (${linkPath}).`,
-      data: {
-        code: "path_conflict",
-        linkPath,
-        targetPath,
-      },
-      error: {
-        code: "path_conflict",
-        message: "Symlink destination exists as a non-link path",
-      },
-    });
+    // Replace stale directory or file with symlink to the canonical location.
+    rmSync(linkPath, { recursive: true, force: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
+    symlinkSync(symlinkTarget, linkPath, "dir");
+    return null;
   }
 
   const existingRawTarget: string = readlinkSync(linkPath);
   const existingAbsoluteTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
   const expectedTarget: string = resolve(targetPath);
   if (existingAbsoluteTarget !== expectedTarget) {
-    return failResult({
-      command: "skills.install",
-      human: `Cannot replace existing link at ${linkPath}; it points to ${existingAbsoluteTarget}.`,
-      data: {
-        code: "path_conflict",
-        linkPath,
-        existingTarget: existingAbsoluteTarget,
-        expectedTarget,
-      },
-      error: {
-        code: "path_conflict",
-        message: "Symlink destination points to a different target",
-      },
-    });
+    // Replace symlink pointing to a different target.
+    rmSync(linkPath, { force: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
+    symlinkSync(symlinkTarget, linkPath, "dir");
+    return null;
   }
 
   rmSync(linkPath, { force: true });
@@ -525,12 +525,16 @@ function updateEditorLink(
 
   const entry = lstatSync(linkPath);
   if (!entry.isSymbolicLink()) {
+    // Replace stale directory or file with symlink to the canonical location.
+    rmSync(linkPath, { recursive: true, force: true });
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return {
       editor,
       linkPath,
       expectedTarget,
-      action: "skipped_conflict",
-      conflictCode: "non_link",
+      action: "refreshed",
+      conflictCode: null,
       existingTarget: null,
     };
   }
@@ -539,12 +543,15 @@ function updateEditorLink(
   const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
 
   if (existingTarget !== expectedTarget) {
+    // Replace symlink pointing to a different target.
+    rmSync(linkPath, { force: true });
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return {
       editor,
       linkPath,
       expectedTarget,
-      action: "skipped_conflict",
-      conflictCode: "wrong_target",
+      action: "refreshed",
+      conflictCode: null,
       existingTarget,
     };
   }

package/src/commands/subtask.ts

@@ -32,13 +32,13 @@ function formatSubtask(subtask: SubtaskRecord): string {
 
 const VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_SUBTASK_LIST_LIMIT = 10;
-const DEFAULT_OPEN_SUBTASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+const DEFAULT_OPEN_SUBTASK_STATUSES = ["in_progress", "todo"] as const;
 const CREATE_OPTIONS = ["task", "t", "title", "description", "d", "status", "s"] as const;
 const LIST_OPTIONS = ["task", "t", "status", "s", "limit", "l", "cursor", "all", "view"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["task", "t", "subtask"] as const;
-const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "owner"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
@@ -113,7 +113,7 @@ function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
 }
 
 function subtaskStatusPriority(status: string): number {
-  if (status === "in_progress" || status === "in-progress") {
+  if (status === "in_progress") {
     return 0;
   }
 
@@ -788,7 +788,8 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
-          readMissingOptionValue(parsed.missingOptionValues, "status", "s");
+          readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
+          readMissingOptionValue(parsed.missingOptionValues, "owner");
         if (missingUpdateOption !== undefined) {
           return failMissingOptionValue("subtask.update", missingUpdateOption);
         }
@@ -801,6 +802,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         const description: string | undefined = readOption(parsed.options, "description", "d");
         const append: string | undefined = readOption(parsed.options, "append");
         const status: string | undefined = readOption(parsed.options, "status", "s");
+        const owner: string | undefined = readOption(parsed.options, "owner");
 
         if (updateAll && ids.length > 0) {
           return failResult({
@@ -923,7 +925,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           append === undefined
             ? description
             : appendLine(domain.getSubtaskOrThrow(subtaskId).description, append);
-        const subtask = mutations.updateSubtask(subtaskId, { title, description: nextDescription, status });
+        const subtask = mutations.updateSubtask(subtaskId, { title, description: nextDescription, status, owner });
 
         return okResult({
           command: "subtask.update",

package/src/commands/suggest.ts

@@ -0,0 +1,283 @@
+import { parseArgs, readOption } from "./arg-parser";
+import { unexpectedFailureResult } from "./error-utils";
+import { resolveSyncStatus } from "./sync-helpers";
+import { buildTaskReadiness, type TaskReadinessResult } from "./task-readiness";
+
+import { TrackerDomain } from "../domain/tracker-domain";
+import { VALID_TRANSITIONS, type EpicRecord, type ValidStatus } from "../domain/types";
+import { okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+import type { SyncStatusSummary } from "../sync/types";
+
+import { DEFAULT_SOURCE_BRANCH } from "./sync-helpers";
+
+const MAX_SUGGESTIONS = 3;
+
+type SuggestionCategory = "recovery" | "sync" | "execution" | "planning";
+
+interface Suggestion {
+  readonly priority: number;
+  readonly action: string;
+  readonly command: string;
+  readonly reason: string;
+  readonly category: SuggestionCategory;
+}
+
+interface SuggestContext {
+  readonly totalEpics: number;
+  readonly activeEpic: string | null;
+  readonly readyTasks: number;
+  readonly blockedTasks: number;
+  readonly inProgressTasks: number;
+  readonly syncBehind: number;
+  readonly pendingConflicts: number;
+}
+
+interface SuggestResult {
+  readonly suggestions: readonly Suggestion[];
+  readonly context: SuggestContext;
+}
+
+function resolveActiveEpic(domain: TrackerDomain, epicId: string | undefined): EpicRecord | null {
+  if (epicId !== undefined) {
+    return domain.getEpic(epicId);
+  }
+
+  const epics = domain.listEpics();
+  const inProgress = epics.find((epic) => epic.status === "in_progress");
+  if (inProgress) {
+    return inProgress;
+  }
+
+  const todo = epics.find((epic) => epic.status === "todo");
+  return todo ?? epics[0] ?? null;
+}
+
+function findInProgressTasks(readiness: TaskReadinessResult): { count: number; first: { id: string; title: string } | null } {
+  let count = 0;
+  let first: { id: string; title: string } | null = null;
+
+  for (const list of [readiness.candidates, readiness.blocked]) {
+    for (const candidate of list) {
+      if (candidate.task.status === "in_progress") {
+        count += 1;
+        if (first === null) {
+          first = { id: candidate.task.id, title: candidate.task.title };
+        }
+      }
+    }
+  }
+
+  return { count, first };
+}
+
+function buildSuggestions(
+  recoveryRequired: boolean,
+  syncSummary: SyncStatusSummary,
+  readiness: TaskReadinessResult,
+  epics: readonly EpicRecord[],
+  activeEpic: EpicRecord | null,
+): readonly Suggestion[] {
+  const suggestions: Suggestion[] = [];
+
+  // Priority 1: Recovery required
+  if (recoveryRequired) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "init",
+      command: "trekoon --toon init",
+      reason: "Storage needs repair — run init to recover",
+      category: "recovery",
+    });
+  }
+
+  // Priority 2: Pending conflicts
+  if (suggestions.length < MAX_SUGGESTIONS && syncSummary.pendingConflicts > 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "sync conflicts",
+      command: "trekoon --toon sync conflicts",
+      reason: `${syncSummary.pendingConflicts} unresolved sync conflict${syncSummary.pendingConflicts === 1 ? "" : "s"} blocking accurate state`,
+      category: "sync",
+    });
+  }
+
+  // Priority 3: Sync behind
+  if (suggestions.length < MAX_SUGGESTIONS && syncSummary.behind > 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `sync pull --from ${syncSummary.sourceBranch}`,
+      command: `trekoon --toon sync pull --from ${syncSummary.sourceBranch}`,
+      reason: `${syncSummary.behind} event${syncSummary.behind === 1 ? "" : "s"} behind ${syncSummary.sourceBranch} branch`,
+      category: "sync",
+    });
+  }
+
+  // Priority 4: In-progress tasks exist
+  const { first: inProgressTask } = findInProgressTasks(readiness);
+  if (suggestions.length < MAX_SUGGESTIONS && inProgressTask !== null) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `continue task ${inProgressTask.id}`,
+      command: `trekoon --toon task show ${inProgressTask.id}`,
+      reason: `In-progress task: ${inProgressTask.title}`,
+      category: "execution",
+    });
+  }
+
+  // Priority 5: Ready tasks available
+  const topReady = readiness.candidates.find((c) => c.task.status !== "in_progress");
+  if (suggestions.length < MAX_SUGGESTIONS && topReady) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `claim task ${topReady.task.id}`,
+      command: `trekoon --toon task update ${topReady.task.id} --status in_progress`,
+      reason: `Highest priority ready task: ${topReady.task.title}`,
+      category: "execution",
+    });
+  }
+
+  // Priority 6: All tasks blocked
+  if (
+    suggestions.length < MAX_SUGGESTIONS
+    && readiness.summary.totalOpenTasks > 0
+    && readiness.summary.readyCount === 0
+    && inProgressTask === null
+  ) {
+    const blockerCount = readiness.summary.unresolvedDependencyCount;
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "review blocked tasks",
+      command: "trekoon --toon task ready",
+      reason: `All ${readiness.summary.blockedCount} open task${readiness.summary.blockedCount === 1 ? " is" : "s are"} blocked by ${blockerCount} unresolved dependenc${blockerCount === 1 ? "y" : "ies"}`,
+      category: "planning",
+    });
+  }
+
+  // Priority 7: All tasks done (epic still open)
+  if (
+    suggestions.length < MAX_SUGGESTIONS
+    && activeEpic !== null
+    && readiness.summary.totalOpenTasks === 0
+    && activeEpic.status !== "done"
+  ) {
+    const epicStatus = activeEpic.status as ValidStatus;
+    const validTargets = VALID_TRANSITIONS.get(epicStatus);
+    const canTransitionToDone = validTargets?.has("done") === true;
+
+    if (canTransitionToDone) {
+      suggestions.push({
+        priority: suggestions.length + 1,
+        action: `mark epic ${activeEpic.id} done`,
+        command: `trekoon --toon epic update ${activeEpic.id} --status done`,
+        reason: `All tasks complete — mark epic "${activeEpic.title}" as done`,
+        category: "planning",
+      });
+    } else if (validTargets?.has("in_progress") === true) {
+      suggestions.push({
+        priority: suggestions.length + 1,
+        action: `advance epic ${activeEpic.id} to in_progress`,
+        command: `trekoon --toon epic update ${activeEpic.id} --status in_progress`,
+        reason: `All tasks complete — advance epic "${activeEpic.title}" to in_progress first (then mark done)`,
+        category: "planning",
+      });
+    }
+  }
+
+  // Priority 8: No epics exist
+  if (suggestions.length < MAX_SUGGESTIONS && epics.length === 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "quickstart",
+      command: "trekoon --toon quickstart",
+      reason: "No epics found — create your first epic with quickstart",
+      category: "planning",
+    });
+  }
+
+  return suggestions.slice(0, MAX_SUGGESTIONS);
+}
+
+function formatSuggestHuman(result: SuggestResult): string {
+  const lines: string[] = [];
+
+  if (result.suggestions.length === 0) {
+    lines.push("No suggestions — tracker state looks good.");
+    return lines.join("\n");
+  }
+
+  lines.push("=== Suggestions ===");
+  for (const suggestion of result.suggestions) {
+    lines.push(`${suggestion.priority}. [${suggestion.category}] ${suggestion.action}`);
+    lines.push(`   Reason: ${suggestion.reason}`);
+    lines.push(`   Command: ${suggestion.command}`);
+  }
+
+  lines.push("");
+  lines.push("=== Context ===");
+  lines.push(`Epics: ${result.context.totalEpics}`);
+  if (result.context.activeEpic !== null) {
+    lines.push(`Active epic: ${result.context.activeEpic}`);
+  }
+  lines.push(`Ready tasks: ${result.context.readyTasks}`);
+  lines.push(`Blocked tasks: ${result.context.blockedTasks}`);
+  lines.push(`In-progress tasks: ${result.context.inProgressTasks}`);
+  lines.push(`Sync behind: ${result.context.syncBehind}`);
+  lines.push(`Pending conflicts: ${result.context.pendingConflicts}`);
+
+  return lines.join("\n");
+}
+
+export async function runSuggest(context: CliContext): Promise<CliResult> {
+  let database: TrekoonDatabase | undefined;
+
+  try {
+    const parsed = parseArgs(context.args);
+    const epicId: string | undefined = readOption(parsed.options, "epic");
+
+    database = openTrekoonDatabase(context.cwd);
+    const diagnostics = database.diagnostics;
+
+    const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
+    const domain = new TrackerDomain(database.db);
+    const epics = domain.listEpics();
+    const activeEpic = resolveActiveEpic(domain, epicId);
+
+    const readiness = buildTaskReadiness(domain, epicId ?? activeEpic?.id);
+
+    const suggestions = buildSuggestions(
+      diagnostics.recoveryRequired,
+      syncSummary,
+      readiness,
+      epics,
+      activeEpic,
+    );
+
+    const result: SuggestResult = {
+      suggestions,
+      context: {
+        totalEpics: epics.length,
+        activeEpic: activeEpic?.id ?? null,
+        readyTasks: readiness.summary.readyCount,
+        blockedTasks: readiness.summary.blockedCount,
+        inProgressTasks: findInProgressTasks(readiness).count,
+        syncBehind: syncSummary.behind,
+        pendingConflicts: syncSummary.pendingConflicts,
+      },
+    };
+
+    return okResult({
+      command: "suggest",
+      human: formatSuggestHuman(result),
+      data: result,
+    });
+  } catch (error: unknown) {
+    return unexpectedFailureResult(error, {
+      command: "suggest",
+      human: "Unexpected suggest command failure",
+    });
+  } finally {
+    database?.close();
+  }
+}

package/src/commands/sync-helpers.ts

@@ -0,0 +1,75 @@
+import type { Database } from "bun:sqlite";
+
+import { countBranchEventsSince } from "../sync/branch-db";
+import { persistGitContext, resolveGitContext } from "../sync/git-context";
+import type { GitContextSnapshot, SyncStatusSummary } from "../sync/types";
+import type { TrekoonDatabase } from "../storage/database";
+
+export const DEFAULT_SOURCE_BRANCH = "main";
+
+export function countAheadLocal(db: Database, currentBranch: string | null, sourceBranch: string): number {
+  if (!currentBranch || currentBranch === sourceBranch) {
+    return 0;
+  }
+
+  const row = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM events
+      WHERE git_branch = @branch;
+      `,
+    )
+    .get({ "@branch": currentBranch }) as { count: number } | null;
+
+  return row?.count ?? 0;
+}
+
+export function countPendingConflictsLocal(db: Database): number {
+  const row = db
+    .query("SELECT COUNT(*) AS count FROM sync_conflicts WHERE resolution = 'pending';")
+    .get() as { count: number } | null;
+
+  return row?.count ?? 0;
+}
+
+export function loadCursorLocal(
+  db: Database,
+  worktreePath: string,
+  sourceBranch: string,
+): { cursor_token: string } | null {
+  return db
+    .query(
+      `
+      SELECT cursor_token
+      FROM sync_cursors
+      WHERE owner_scope = 'worktree'
+        AND owner_worktree_path = ?
+        AND source_branch = ?
+      LIMIT 1;
+      `,
+    )
+    .get(worktreePath, sourceBranch) as { cursor_token: string } | null;
+}
+
+export function resolveSyncStatus(
+  database: TrekoonDatabase,
+  cwd: string,
+  sourceBranch: string,
+): SyncStatusSummary {
+  const git: GitContextSnapshot = resolveGitContext(cwd);
+  persistGitContext(database.db, git);
+
+  const cursor = loadCursorLocal(database.db, git.worktreePath, sourceBranch);
+  const cursorToken: string = cursor?.cursor_token ?? "0:";
+  const onSourceBranch: boolean = git.branchName !== null && git.branchName === sourceBranch;
+
+  return {
+    sourceBranch,
+    ahead: countAheadLocal(database.db, git.branchName, sourceBranch),
+    behind: onSourceBranch ? 0 : countBranchEventsSince(database.db, sourceBranch, cursorToken),
+    pendingConflicts: countPendingConflictsLocal(database.db),
+    sameBranch: onSourceBranch,
+    git,
+  };
+}