trekoon 0.3.7 → 0.3.8

package/src/commands/board.ts

@@ -121,7 +121,7 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
         return okResult({
           command: "board.open",
           human: [
-            `Board ready at ${server.url}`,
+            `Board ready at ${server.fallbackUrl}`,
             launch.launched
               ? `Browser launched with ${launch.command}`
               : `Browser launch failed: ${launch.errorMessage ?? "unknown failure"}`,

package/src/commands/quickstart.ts

@@ -4,6 +4,16 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 const QUICKSTART_TEXT = [
   "Trekoon quickstart",
   "",
+  "Human workflow:",
+  "  1. Gather context through discussion, brainstorming, or research.",
+  "  2. Run: trekoon plan <goal>",
+  "     Use this when you want Trekoon to turn the goal into an execution-ready epic.",
+  "  3. Run: trekoon <epic-id>",
+  "     Use this to inspect the epic, next ready work, and blockers before execution.",
+  "  4. Run: trekoon <epic-id> execute",
+  "     Use this when you want the agent to keep working until the epic is done,",
+  "     all remaining work is blocked, or it needs your input.",
+  "",
   "Agents: always use --toon on every command.",
   "Aligned with: .agents/skills/trekoon/SKILL.md",
   "",

package/src/domain/mutation-service.ts

@@ -1,7 +1,7 @@
 import { type Database } from "bun:sqlite";
 
 import { writeTransaction } from "../storage/database";
-import { appendEventWithGitContext, withTransactionEventContext } from "../sync/event-writes";
+import { appendEventWithGitContext, prepareEventWriteContext, withTransactionEventContext } from "../sync/event-writes";
 import { ENTITY_OPERATIONS } from "./mutation-operations";
 import { TrackerDomain, validateStatusTransition } from "./tracker-domain";
 import {
@@ -49,6 +49,8 @@ type AtomicIdempotentMutationResult =
   | AtomicIdempotencyReplayResult
   | AtomicIdempotencyCompletedResult;
 
+const BOARD_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
 function countMatches(value: string, searchText: string): number {
   if (searchText.length === 0) {
     return 0;
@@ -128,7 +130,49 @@ export class MutationService {
   }
 
   #writeTransaction<T>(fn: () => T): T {
-    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, this.#cwd, fn));
+    const eventContext = prepareEventWriteContext(this.#db, this.#cwd);
+    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, eventContext, fn));
+  }
+
+  #dependencyEventEntityId(input: {
+    sourceId: string;
+    sourceKind: string;
+    dependsOnId: string;
+    dependsOnKind: string;
+  }): string {
+    return `${input.sourceKind}:${input.sourceId}->${input.dependsOnKind}:${input.dependsOnId}`;
+  }
+
+  #dependencyEventFields(input: {
+    dependencyId?: string | undefined;
+    sourceId: string;
+    sourceKind?: string | undefined;
+    dependsOnId: string;
+    dependsOnKind?: string | undefined;
+    sourceEventId?: string | undefined;
+  }): Record<string, string> {
+    const fields: Record<string, string> = {
+      source_id: input.sourceId,
+      depends_on_id: input.dependsOnId,
+    };
+
+    if (input.dependencyId) {
+      fields.dependency_id = input.dependencyId;
+    }
+
+    if (input.sourceKind) {
+      fields.source_kind = input.sourceKind;
+    }
+
+    if (input.dependsOnKind) {
+      fields.depends_on_kind = input.dependsOnKind;
+    }
+
+    if (input.sourceEventId) {
+      fields.source_event_id = input.sourceEventId;
+    }
+
+    return fields;
   }
 
   createEpic(input: { title: string; description: string; status?: string | undefined }): EpicRecord {
@@ -185,12 +229,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return {
@@ -293,12 +343,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return created;
@@ -349,16 +405,19 @@ export class MutationService {
       }
 
       for (const dependency of plan.touchingDependencies) {
-        this.#appendEntityEvent(
-          "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
-          ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: taskDeleteEventId,
-          },
-        );
+          this.#appendEntityEvent(
+            "dependency",
+            this.#dependencyEventEntityId(dependency),
+            ENTITY_OPERATIONS.dependency.removed,
+            this.#dependencyEventFields({
+              dependencyId: dependency.id,
+              sourceId: dependency.sourceId,
+              sourceKind: dependency.sourceKind,
+              dependsOnId: dependency.dependsOnId,
+              dependsOnKind: dependency.dependsOnKind,
+              sourceEventId: taskDeleteEventId,
+            }),
+          );
       }
 
       return {
@@ -454,13 +513,16 @@ export class MutationService {
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          this.#dependencyEventEntityId(dependency),
           ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: subtaskDeleteEventId,
-          },
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
         );
       }
       return {
@@ -489,13 +551,16 @@ export class MutationService {
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          this.#dependencyEventEntityId(dependency),
           ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: subtaskDeleteEventId,
-          },
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
         );
       }
 
@@ -516,12 +581,18 @@ export class MutationService {
   addDependency(sourceId: string, dependsOnId: string): DependencyRecord {
     return this.#writeTransaction((): DependencyRecord => {
       const dependency = this.#domain.addDependency(sourceId, dependsOnId);
-      this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-        source_id: dependency.sourceId,
-        source_kind: dependency.sourceKind,
-        depends_on_id: dependency.dependsOnId,
-        depends_on_kind: dependency.dependsOnKind,
-      });
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
       return dependency;
     });
   }
@@ -534,12 +605,18 @@ export class MutationService {
   }): AtomicIdempotentMutationResult {
     return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
       const dependency = this.#domain.addDependency(input.sourceId, input.dependsOnId);
-      this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-        source_id: dependency.sourceId,
-        source_kind: dependency.sourceKind,
-        depends_on_id: dependency.dependsOnId,
-        depends_on_kind: dependency.dependsOnKind,
-      });
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
       return {
         state: "completed",
         status: 201,
@@ -552,12 +629,18 @@ export class MutationService {
     return this.#writeTransaction((): CompactDependencyBatchAddResult => {
       const created = this.#domain.addDependencyBatch(input);
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
       return created;
     });
@@ -565,12 +648,22 @@ export class MutationService {
 
   removeDependency(sourceId: string, dependsOnId: string): number {
     return this.#writeTransaction((): number => {
+      const existingDependency = this.#domain.listDependencies(sourceId)
+        .find((dependency) => dependency.dependsOnId === dependsOnId);
       const removed = this.#domain.removeDependency(sourceId, dependsOnId);
       if (removed > 0) {
-        this.#appendEntityEvent("dependency", `${sourceId}->${dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
-          source_id: sourceId,
-          depends_on_id: dependsOnId,
-        });
+        this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+          sourceId,
+          sourceKind: existingDependency?.sourceKind ?? "task",
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+        }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+          dependencyId: existingDependency?.id,
+          sourceId,
+          sourceKind: existingDependency?.sourceKind,
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind,
+        }));
       }
       return removed;
     });
@@ -589,9 +682,10 @@ export class MutationService {
     }) => Record<string, unknown>;
   }): AtomicIdempotentMutationResult {
     return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
-      const existingDependencyIds = this.#domain.listDependencies(input.sourceId)
-        .filter((dependency) => dependency.dependsOnId === input.dependsOnId)
-        .map((dependency) => dependency.id);
+      const existingDependencies = this.#domain.listDependencies(input.sourceId)
+        .filter((dependency) => dependency.dependsOnId === input.dependsOnId);
+      const existingDependencyIds = existingDependencies.map((dependency) => dependency.id);
+      const existingDependency = existingDependencies[0];
       const removed = this.#domain.removeDependency(input.sourceId, input.dependsOnId);
       if (removed === 0) {
         throw new DomainError({
@@ -603,10 +697,18 @@ export class MutationService {
           },
         });
       }
-      this.#appendEntityEvent("dependency", `${input.sourceId}->${input.dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
-        source_id: input.sourceId,
-        depends_on_id: input.dependsOnId,
-      });
+      this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind ?? "task",
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+      }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+        dependencyId: existingDependency?.id,
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind,
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind,
+      }));
       return {
         state: "completed",
         status: 200,
@@ -741,6 +843,7 @@ export class MutationService {
     mutate: () => AtomicIdempotencyCompletedResult,
   ): AtomicIdempotentMutationResult {
     return this.#writeTransaction((): AtomicIdempotentMutationResult => {
+      this.#pruneExpiredIdempotencyKeys();
       const inserted = this.#db.query(
         `
         INSERT INTO board_idempotency_keys (
@@ -816,6 +919,17 @@ export class MutationService {
     });
   }
 
+  #pruneExpiredIdempotencyKeys(now: number = Date.now()): void {
+    const cutoff: number = now - BOARD_IDEMPOTENCY_RETENTION_MS;
+    this.#db.query(
+      `
+      DELETE FROM board_idempotency_keys
+      WHERE state = 'completed'
+        AND created_at < ?;
+      `,
+    ).run(cutoff);
+  }
+
   #previewScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,

package/src/domain/tracker-domain.ts

@@ -165,6 +165,20 @@ function normalizeSubtaskDescription(value: string | undefined): string {
   return value.trim();
 }
 
+function normalizeOwner(value: string | null | undefined): string | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value === null) {
+    return null;
+  }
+
+  const normalized = value.trim()
+  ;
+  return normalized.length > 0 ? normalized : null;
+}
+
 function isValidStatus(status: string): status is ValidStatus {
   return (VALID_STATUSES as readonly string[]).includes(status);
 }
@@ -526,7 +540,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
-    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
+    const nextOwner: string | null = input.owner !== undefined ? normalizeOwner(input.owner) ?? null : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "task", existing.status, nextStatus);
     const now: number = Date.now();
 
@@ -777,7 +791,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? normalizeSubtaskDescription(input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
-    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
+    const nextOwner: string | null = input.owner !== undefined ? normalizeOwner(input.owner) ?? null : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "subtask", existing.status, nextStatus);
     const now: number = Date.now();
 

package/src/storage/migrations.ts

@@ -105,6 +105,14 @@ const BOARD_IDEMPOTENCY_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
   "DROP TABLE IF EXISTS board_idempotency_keys;",
 ];
 
+const BOARD_IDEMPOTENCY_RETENTION_INDEX_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_board_idempotency_state_created_at ON board_idempotency_keys(state, created_at);",
+];
+
+const BOARD_IDEMPOTENCY_RETENTION_INDEX_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_board_idempotency_state_created_at;",
+];
+
 function tableHasColumn(db: Database, tableName: string, columnName: string): boolean {
   const columns = db.query(`PRAGMA table_info(${tableName});`).all() as Array<{ name: string }>;
   return columns.some((column) => column.name === columnName);
@@ -359,6 +367,20 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 10,
+    name: "0010_board_idempotency_retention_index",
+    up(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_RETENTION_INDEX_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_RETENTION_INDEX_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {
@@ -557,6 +579,11 @@ export function migrateDatabase(db: Database): void {
     ensureMigrationTable(db);
     ensureMigrationVersionColumn(db);
 
+    // Backfill the legacy board_idempotency_keys.state column before running
+    // any migrations so that later migrations (e.g. 0010's state-scoped index)
+    // can assume the column exists on databases whose 0009 predates it.
+    migrateBoardIdempotencyState(db);
+
     const version: number = currentVersion(db);
 
     for (const migration of MIGRATIONS) {
@@ -567,8 +594,6 @@ export function migrateDatabase(db: Database): void {
       migration.up(db);
       recordMigration(db, migration);
     }
-
-    migrateBoardIdempotencyState(db);
   });
 }
 

package/src/storage/schema.ts

@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `PRAGMA foreign_keys = ON;`,
@@ -137,4 +137,5 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution ON sync_conflicts(resolution);`,
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution_entity_field_id ON sync_conflicts(resolution, entity_id, field_name, id);`,
   `CREATE INDEX IF NOT EXISTS idx_board_idempotency_created_at ON board_idempotency_keys(created_at);`,
+  `CREATE INDEX IF NOT EXISTS idx_board_idempotency_state_created_at ON board_idempotency_keys(state, created_at);`,
 ];

package/src/sync/event-writes.ts

@@ -38,18 +38,22 @@ export function nextEventTimestamp(db: Database): number {
   return Math.max(now, latestEvent.created_at + 1);
 }
 
-export function withTransactionEventContext<T>(db: Database, cwd: string, fn: () => T): T {
-  const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
-  if (existingContext) {
-    return fn();
-  }
-
+export function prepareEventWriteContext(db: Database, cwd: string): EventWriteContext {
   const nextTimestamp: number = nextEventTimestamp(db);
   const git: ResolvedGitContext = resolveGitContext(cwd, nextTimestamp);
-  const context: EventWriteContext = {
+
+  return {
     git,
     nextTimestamp,
   };
+}
+
+export function withTransactionEventContext<T>(db: Database, context: EventWriteContext, fn: () => T): T {
+  const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
+  if (existingContext) {
+    return fn();
+  }
+
   transactionEventContexts.set(db, context);
 
   try {