trekoon 0.4.4 → 0.4.6

package/src/storage/database.ts

@@ -398,6 +398,57 @@ export function openTrekoonDatabase(
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
 
+  // Open-time read+write throughput tuning. WAL is required (set above);
+  // the rest are layered on top.
+  //
+  // synchronous: WAL+NORMAL is the documented standard pairing
+  // (https://www.sqlite.org/wal.html#performance_considerations) — durability
+  // semantics: on a hard kernel/OS crash the last unfsynced transactions can
+  // be lost, but the DB file itself never corrupts. Operators who want the
+  // pre-tuning behaviour (synchronous=FULL) can set
+  // TREKOON_SQLITE_DURABILITY=full at open time.
+  const durabilityMode: string = (process.env.TREKOON_SQLITE_DURABILITY ?? "").toLowerCase();
+  if (durabilityMode === "full") {
+    db.exec("PRAGMA synchronous = FULL;");
+  } else {
+    db.exec("PRAGMA synchronous = NORMAL;");
+  }
+
+  // temp_store=MEMORY keeps temp B-tree sorts and intermediate result sets
+  // out of the temp file on disk — most relevant for the ORDER BY paths
+  // that pre-0013 schemas relied on temp-b-tree sorts for.
+  db.exec("PRAGMA temp_store = MEMORY;");
+
+  // mmap_size: opportunistic memory-mapped reads for the first 256 MiB of
+  // the DB file. Reduces read syscall overhead for hot pages. bun:sqlite
+  // forwards the PRAGMA to libsqlite3; the connection will silently keep
+  // the previous value if the platform does not support mmap.
+  db.exec("PRAGMA mmap_size = 268435456;");
+
+  // cache_size negative value -> KiB, positive value -> pages.
+  // Default: 64 MiB. Override with TREKOON_SQLITE_CACHE_MIB (integer MiB).
+  // Negative values are rejected. With 16-handle daemon mode the per-process
+  // page cache approaches CACHED_DATABASES_CAPACITY × cache_size, so
+  // operators should lower TREKOON_SQLITE_CACHE_MIB (e.g. to 16) when memory
+  // is constrained.
+  const cacheMibRaw: string = (process.env.TREKOON_SQLITE_CACHE_MIB ?? "").trim();
+  const cacheMib: number = cacheMibRaw.length > 0 ? Number(cacheMibRaw) : 64;
+  if (!Number.isInteger(cacheMib) || cacheMib < 0) {
+    throw new DomainError({
+      code: "invalid_input",
+      message:
+        `TREKOON_SQLITE_CACHE_MIB must be a non-negative integer (got ${JSON.stringify(cacheMibRaw)}).`,
+      details: { envVar: "TREKOON_SQLITE_CACHE_MIB", provided: cacheMibRaw },
+    });
+  }
+  db.exec(`PRAGMA cache_size = ${-(cacheMib * 1024)};`);
+
+  // Trigger a checkpoint roughly every 1000 frames so the WAL file does
+  // not grow unbounded under sustained writes. Default is 1000 already,
+  // but we pin it explicitly so the value cannot drift if libsqlite3
+  // changes its default in a future bump.
+  db.exec("PRAGMA wal_autocheckpoint = 1000;");
+
   if (options.autoMigrate ?? true) {
     migrateDatabase(db);
   }
@@ -429,8 +480,22 @@ export function openTrekoonDatabase(
     paths,
     diagnostics,
     close(): void {
-      db.exec("PRAGMA wal_checkpoint(PASSIVE);");
-      db.close(false);
+      // Best-effort checkpoint: matches closeCachedHandle's posture. WAL
+      // checkpointing is maintenance, not durability — skipping it cannot
+      // corrupt the DB. Suppressing errors here lets read-only contexts
+      // (read-only filesystem, immutable DB file, sandboxed agents) close
+      // cleanly instead of throwing SQLITE_READONLY on the very last
+      // syscall before db.close().
+      try {
+        db.exec("PRAGMA wal_checkpoint(PASSIVE);");
+      } catch {
+        /* best effort — checkpoint is maintenance, not durability */
+      }
+      try {
+        db.close(false);
+      } catch {
+        /* best effort — handle may already be closing */
+      }
     },
   };
 }

package/src/storage/migrations.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { Database } from "bun:sqlite";
 
 import { DomainError } from "../domain/types";
-import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
+import { BASE_SCHEMA_REVISION, BASE_SCHEMA_STATEMENTS } from "./schema";
 
 const BACKUP_HINT = "Run 'trekoon migrate backup' to snapshot .trekoon/trekoon.db before any manual recovery.";
 
@@ -23,7 +23,7 @@ function migrationDownUnsupported(migrationName: string, version: number): Domai
 }
 
 const BASE_MIGRATION_VERSION = 1;
-const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
+const BASE_MIGRATION_NAME = `0001_base_schema_v${BASE_SCHEMA_REVISION}`;
 const LEGACY_BASE_MIGRATION_NAME_PATTERNS: readonly string[] = [
   "0001_base_schema_v*",
 ];
@@ -138,6 +138,116 @@ const SYNC_CONFLICTS_SCOPE_DOWN_STATEMENTS: readonly string[] = [
   "DROP INDEX IF EXISTS idx_sync_conflicts_scope_resolution;",
 ];
 
+const TASK_ORDERED_SCAN_INDEX_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_tasks_epic_created ON tasks(epic_id, created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_subtasks_task_created ON subtasks(task_id, created_at, id);",
+];
+
+const TASK_ORDERED_SCAN_INDEX_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_subtasks_task_created;",
+  "DROP INDEX IF EXISTS idx_tasks_epic_created;",
+];
+
+const DEPENDENCY_KIND_INDEX_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS uniq_dependencies_edge;",
+  "DROP INDEX IF EXISTS idx_dependencies_target;",
+  "DROP INDEX IF EXISTS idx_dependencies_source;",
+  // v12 dropped the v2 single-column source/target indexes to make room for
+  // the composite versions of the same names. Restore the v2 indexes on
+  // rollback so v11 lookups continue to benefit from them.
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_depends_on ON dependencies(depends_on_id);",
+];
+
+/**
+ * Migration 0012: dedupe dependency rows that share the full polymorphic
+ * edge (source_id, source_kind, depends_on_id, depends_on_kind), then add
+ * a source-side composite index, a target-side composite index, and a
+ * UNIQUE index on the full 4-column edge. This closes the polymorphic-FK
+ * gap left by 0005 (which made (source_id, depends_on_id) unique but did
+ * not include kind columns in the UNIQUE constraint).
+ *
+ * Step 1 is idempotent: the DELETE is a no-op when no duplicates exist.
+ * The dedupe keeps the row with the lowest created_at per logical edge.
+ * The dropped duplicates are not recoverable — rollback only drops the
+ * indexes; the migration is irreversibly destructive of duplicate rows,
+ * which is why down() throws migration_down_unsupported.
+ */
+function migrateDependencyKindIndexes(db: Database): void {
+  // Defensive: skip the migration entirely if the dependencies table is
+  // missing. This guards partial-schema test fixtures (and any future
+  // legacy DBs that arrive without the v1 base schema) the same way
+  // migrateSyncConflictsScope and migrateBoardIdempotencyState do.
+  if (!tableExists(db, "dependencies")) {
+    return;
+  }
+
+  // Step 1: dedupe rows that share the full edge, keeping the lowest
+  // created_at survivor (tiebreak on id for determinism). Performed under
+  // the same exclusive transaction the migration runner holds.
+  //
+  // EXISTS guard: skip the expensive window-function DELETE entirely when
+  // the table has no duplicate edges. This avoids a full-table scan on
+  // clean databases and prevents spurious console.warn output.
+  const hasDuplicates = db
+    .query(
+      `
+      SELECT 1 FROM dependencies
+      GROUP BY source_id, source_kind, depends_on_id, depends_on_kind
+      HAVING count(*) > 1
+      LIMIT 1;
+      `,
+    )
+    .get() as Record<string, unknown> | null;
+
+  if (hasDuplicates !== null) {
+    const dedupeResult = db
+      .query(
+        `
+        DELETE FROM dependencies
+        WHERE id NOT IN (
+          SELECT id FROM (
+            SELECT id,
+                   ROW_NUMBER() OVER (
+                     PARTITION BY source_id, source_kind, depends_on_id, depends_on_kind
+                     ORDER BY created_at ASC, id ASC
+                   ) AS rn
+            FROM dependencies
+          )
+          WHERE rn = 1
+        );
+        `,
+      )
+      .run();
+
+    const dedupedCount: number = Number(dedupeResult.changes ?? 0);
+    if (dedupedCount > 0) {
+      console.warn(
+        `[trekoon] migration 0012_dependency_kind_indexes: removed ${dedupedCount} duplicate dependency edge(s) ` +
+          "before adding uniq_dependencies_edge UNIQUE index (irreversible).",
+      );
+    }
+  }
+
+  // Step 2: indexes that accelerate the polymorphic listDependencies /
+  // listReverseDependencies / addDependency lookup paths.
+  //
+  // v2 already created single-column idx_dependencies_source(source_id) and
+  // idx_dependencies_depends_on(depends_on_id). Replace both with composite
+  // (id, kind) indexes — the source-side keeps the v2 name so the schema
+  // surface stays minimal, the target-side gets a new idx_dependencies_target
+  // name. We drop the v2 indexes first because CREATE INDEX IF NOT EXISTS
+  // would otherwise be a no-op against the existing single-column index of
+  // the same name.
+  db.exec("DROP INDEX IF EXISTS idx_dependencies_source;");
+  db.exec("DROP INDEX IF EXISTS idx_dependencies_depends_on;");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id, source_kind);");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(depends_on_id, depends_on_kind);");
+  db.exec(
+    "CREATE UNIQUE INDEX IF NOT EXISTS uniq_dependencies_edge ON dependencies(source_id, source_kind, depends_on_id, depends_on_kind);",
+  );
+}
+
 function migrateSyncConflictsScope(db: Database): void {
   if (!tableExists(db, "sync_conflicts")) {
     return;
@@ -454,6 +564,43 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 12,
+    name: "0012_dependency_kind_indexes",
+    up(db: Database): void {
+      migrateDependencyKindIndexes(db);
+    },
+    down(db: Database): void {
+      // up() deduplicates rows sharing the full polymorphic edge
+      // (source_id, source_kind, depends_on_id, depends_on_kind); those
+      // row deletions are unrecoverable. down() therefore drops only the
+      // new indexes — schema-level recovery — and leaves data restoration
+      // to operators (see the migrate help notes for the backup workflow).
+      for (const statement of DEPENDENCY_KIND_INDEX_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 13,
+    name: "0013_task_ordered_scan_indexes",
+    up(db: Database): void {
+      // Guard against partial-schema fixtures the same way 0011/0012 do.
+      // If tasks or subtasks are missing the base v1 schema never ran;
+      // there is nothing to index against.
+      if (!tableExists(db, "tasks") || !tableExists(db, "subtasks")) {
+        return;
+      }
+      for (const statement of TASK_ORDERED_SCAN_INDEX_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of TASK_ORDERED_SCAN_INDEX_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {

package/src/storage/schema.ts

@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 3;
+export const BASE_SCHEMA_REVISION = 5;
 
 export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `PRAGMA foreign_keys = ON;`,
@@ -142,4 +142,9 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS idx_sync_conflicts_scope_resolution ON sync_conflicts(worktree_path, current_branch, resolution);`,
   `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);`,
+  `CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id, source_kind);`,
+  `CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(depends_on_id, depends_on_kind);`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS uniq_dependencies_edge ON dependencies(source_id, source_kind, depends_on_id, depends_on_kind);`,
+  `CREATE INDEX IF NOT EXISTS idx_tasks_epic_created ON tasks(epic_id, created_at, id);`,
+  `CREATE INDEX IF NOT EXISTS idx_subtasks_task_created ON subtasks(task_id, created_at, id);`,
 ];

package/src/sync/event-writes.ts

@@ -14,6 +14,16 @@ interface EventRecordInput {
 interface EventWriteContext {
   readonly git: ResolvedGitContext;
   nextTimestamp: number;
+  /**
+   * Transaction-scoped guard: `persistGitContext` upserts the same
+   * (worktree_path, branch_name, head_sha) row on every call, so doing it
+   * once per appended event row is wasted IO under bulk creates. The first
+   * `appendEventWithGitContext` inside the transaction flips this to `true`;
+   * subsequent appends within the same write lock skip the upsert. Per-event
+   * rows still carry `git_branch` / `git_head` from `context.git`, so the
+   * events-table contract is unchanged.
+   */
+  gitPersisted: boolean;
 }
 
 const transactionEventContexts: WeakMap<Database, EventWriteContext> = new WeakMap();
@@ -79,7 +89,7 @@ export function withTransactionEventContext<T>(db: Database, git: ResolvedGitCon
   // subprocess invocations happen here.
   const nextTimestamp: number = nextEventTimestamp(db);
   const resolvedGit: ResolvedGitContext = { ...git, persistedAt: nextTimestamp };
-  const context: EventWriteContext = { git: resolvedGit, nextTimestamp };
+  const context: EventWriteContext = { git: resolvedGit, nextTimestamp, gitPersisted: false };
 
   transactionEventContexts.set(db, context);
 
@@ -101,7 +111,19 @@ export function appendEventWithGitContext(
   const git: ResolvedGitContext = context?.git ?? resolveGitContext(cwd, now);
   const eventId: string = randomUUID();
 
-  persistGitContext(db, git, now);
+  // Bulk mutations append many events under one BEGIN IMMEDIATE write lock.
+  // persistGitContext upserts the same (worktree_path, branch_name, head_sha)
+  // row every call, so we only need it once per transaction. Inside a
+  // transaction context the first call flips `gitPersisted` to `true` and
+  // subsequent appends skip the redundant upsert. Single-event paths (no
+  // active transaction context) still upsert on every call — preserving
+  // existing behaviour for direct callers like sync-helpers.
+  if (context === undefined) {
+    persistGitContext(db, git, now);
+  } else if (!context.gitPersisted) {
+    persistGitContext(db, git, now);
+    context.gitPersisted = true;
+  }
 
   if (context) {
     context.nextTimestamp += 1;

package/.agents/skills/trekoon/reference/execution-with-team.md

@@ -1,161 +0,0 @@
-# Execution With Agent Teams Reference
-
-You are a team lead orchestrator. Use this file only for Claude Code Agent
-Teams when the user explicitly asks for team execution and
-`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`. This is a runtime-specific path,
-not the default subagent path for Codex, OpenCode, Pi, or other harnesses.
-
-Team execution is complete only when the epic is marked `done`, all remaining
-work is blocked with recorded reasons, or real user input is required.
-
-Clarify meaningful ambiguity before starting.
-
-## Start
-
-Build the graph with the standard execution reference: `task ready`,
-`dep reverse`, lane grouping, and first-wave validation. Then mark the epic in
-progress:
-
-```bash
-trekoon --toon epic update <epic-id> --status in_progress
-```
-
-## Create Team And Tasks
-
-1. Create the team:
-
-```text
-TeamCreate:
-  team_name: "<epic-slug>"
-  description: "Executing epic <epic-id>: <title>"
-```
-
-2. Create one shared team task per lane:
-
-```text
-TaskCreate:
-  subject: "<lane>: <task-ids/titles>"
-  description: |
-    Execute these Trekoon tasks IN ORDER unless task descriptions allow
-    parallel subtasks:
-    - Task <id>: <title>
-
-    Before each task:
-    - trekoon --toon task claim <id> --owner <lane-name>
-    - trekoon --toon task update <id> --append "Starting implementation"
-
-    While working:
-    - Complete required subtasks.
-    - Append progress notes; do not rewrite task descriptions.
-    - Use task done for completion.
-    - Use --compact for noisy Trekoon reads.
-
-    On completion:
-    - Append verification evidence.
-    - trekoon --toon task done <id>
-    - Report unblocked tasks, open subtask warnings, and next candidate via
-      SendMessage.
-    - Report review result or review gap for non-trivial code changes.
-
-    If blocked:
-    - Append blocker reason, dependency id, and exact failing command/output.
-    - trekoon --toon task update <id> --append "Blocked by <reason>" --status blocked
-    - Notify team lead via SendMessage.
-
-    Do not create branches, commits, pushes, or PRs unless the user explicitly
-    asked and harness policy allows it.
-```
-
-Use `blockedBy` via TaskUpdate for team tasks that must run sequentially.
-
-3. Spawn one teammate per parallel lane:
-
-```text
-Agent:
-  name: "developer-1"
-  team_name: "<epic-slug>"
-  subagent_type: "general-purpose"
-  description: "<lane>: <task titles>"
-  prompt: |
-    You are a developer on team "<epic-slug>".
-    Work through your TaskList assignment.
-    Claim each Trekoon task before editing:
-      trekoon --toon task claim <trekoon-task-id> --owner <your-name>
-
-    Use task done for completion. Read and report unblocked tasks, warnings,
-    and next candidate via SendMessage.
-
-    Communicate blockers and coordination needs via SendMessage.
-```
-
-Use 3-5 teammates for most epics. Do not over-parallelize. Use
-`general-purpose` for implementation and `Explore`/`Plan` only for read-only
-research or planning.
-
-## Coordinate
-
-Your job as team lead:
-
-1. Monitor SendMessage updates.
-2. When a teammate reports `unblocked` tasks from `task done`, create new team
-   tasks and assign idle teammates.
-3. Help resolve or reassign blockers.
-4. Keep Trekoon owners current:
-   ```bash
-   trekoon --toon task update <task-id> --owner <teammate-name>
-   ```
-5. Use SendMessage to direct teammates.
-6. Check progress:
-   ```bash
-   trekoon --toon epic progress <epic-id>
-   ```
-7. When all teammates are blocked, run:
-   ```bash
-   trekoon --toon suggest --epic <epic-id>
-   ```
-
-## Recovery
-
-Use the standard execution recovery rules. Teammates should try to fix failures
-with their local context. If they cannot, they must report exact command/output
-via SendMessage so you can give fix instructions or reassign.
-
-For `status_transition_invalid`, inspect current status with:
-
-```bash
-trekoon --toon --compact task show <id>
-```
-
-For `dependency_blocked`, inspect the dependency, append a blocker note, then
-continue with a ready candidate from:
-
-```bash
-trekoon --toon task ready --epic <epic-id>
-```
-
-## Verify And Close
-
-Use the standard execution verification rules: review, automated tests, manual
-checks, DX quality, and Trekoon evidence notes.
-
-After all work is verified:
-
-```bash
-trekoon --toon epic progress <epic-id>
-trekoon --toon suggest --epic <epic-id>
-trekoon --toon epic update <epic-id> --status done
-```
-
-Then send `shutdown_request` to each teammate, delete the team with TeamDelete,
-and return completed tasks, files changed, verification, review, remaining
-blockers, and dependency state.
-
-## Team Tools
-
-| Purpose | Tool |
-|---|---|
-| Create team | `TeamCreate` |
-| Manage shared tasks | `TaskCreate` / `TaskList` / `TaskUpdate` / `TaskGet` |
-| Spawn teammates | `Agent` with `team_name` |
-| Communicate | `SendMessage` |
-| Clean up | `TeamDelete` |