trekoon 0.2.1 → 0.2.4

package/src/commands/quickstart.ts

@@ -7,28 +7,42 @@ const QUICKSTART_TEXT = [
   "This quickstart is aligned with .agents/skills/trekoon/SKILL.md.",
   "For agents: always use --toon for every command.",
   "",
-  "1) Local DB and worktree model",
-  "- Every worktree stores tracker state at .trekoon/trekoon.db.",
-  "- This DB stays local; it is not merged by Git automatically.",
+  "1) Shared storage model",
+  "- In git repos and worktrees, Trekoon resolves one repo-scoped .trekoon directory.",
+  "- Every worktree for the same repo points at the same .trekoon/trekoon.db file.",
+  "- Keep .trekoon gitignored: the SQLite DB is live operational state, not source.",
+  "- Committing the DB is the wrong fix for setup drift because it snapshots machine-local state.",
   "",
-  "2) Agent session-start checklist (verify setup + current state)",
-  "- 1. Verify tracker exists (or initialize once): trekoon --toon init",
-  "- 2. Check sync baseline: trekoon --toon sync status",
-  "- 3. Load active context: trekoon --toon epic list",
-  "- 4. Load active tasks: trekoon --toon task list",
-  "- 5. Load deterministic candidates: trekoon --toon task ready --limit 5",
-  "- 6. If blocked, inspect downstream impact: trekoon --toon dep reverse <task-or-subtask-id>",
+  "2) Bootstrap and agent startup (primary)",
+  "- Single call: trekoon --toon session",
+  "- Replaces: init + sync status + task next + dep list + task show in one call.",
+  "- Returns diagnostics, next ready task, its dependencies, and full task payload.",
+  "- If diagnostics show recoveryRequired or a tracked/ignored mismatch, stop and repair setup.",
+  "- Do not continue after storage mismatch, ambiguous recovery, or broken bootstrap warnings.",
+  "- In worktrees, confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root.",
+  "",
+  "2a) Bootstrap (manual/legacy — use session instead)",
+  "- 1. Initialize or verify shared storage: trekoon --toon init",
+  "- 2. Read machine diagnostics: trekoon --toon sync status",
+  "- 3. Select next task: trekoon --toon task next",
+  "- 4. Check dependencies: trekoon --toon dep list <task-id>",
+  "- 5. Show full task: trekoon --toon task show <task-id> --all",
   "",
   "3) AI execution loop (deterministic, dependency-aware)",
-  "- 1. Sync branch/worktree state: trekoon --toon sync status",
-  "- 2. Select ready work: trekoon --toon task ready --limit 5",
-  "- 3. Pick top candidate when needed: trekoon --toon task next",
-  "- 4. Check downstream blockers: trekoon --toon dep reverse <task-or-subtask-id>",
-  "- 5. Claim work and update status: trekoon --toon task update <task-id> --status in_progress",
-  "- 6. Complete with context: trekoon --toon task update <task-id> --append \"Completed implementation\" --status done",
-  "- 7. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
+  "- 1. Start or resume session: trekoon --toon session",
+  "- 2. Claim work: trekoon --toon task update <task-id> --status in_progress",
+  "- 3. Complete with context: trekoon --toon task done <task-id> --append \"Completed implementation\"",
+  "  - Replaces: update status done + task next + dep list + task show in one call.",
+  "  - Returns next ready task, its dependencies, and full task payload.",
+  "- 4. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
+  "",
+  "4) Worktree diagnostics and recovery",
+  "- Read machine fields when available: storageMode, repoCommonDir, worktreeRoot, sharedStorageRoot, databaseFile.",
+  "- sharedStorageRoot differs from worktreeRoot in linked worktrees; that is expected and should be visible.",
+  "- If recoveryRequired is true, run trekoon --toon init and follow the reported recovery action before more commands.",
+  "- If tracked and ignored storage disagree, delete the bad fix in Git and re-bootstrap local storage instead.",
   "",
-  "4) Power-user command patterns (aligned with skill)",
+  "5) Power-user command patterns (aligned with skill)",
   "- Inspect full epic tree: trekoon --toon epic show <epic-id> --all",
   "- Inspect full task payload: trekoon --toon task show <task-id> --all",
   "- Check direct dependencies before starting: trekoon --toon dep list <task-id>",
@@ -37,7 +51,7 @@ const QUICKSTART_TEXT = [
   "- Paginate deterministically: trekoon --toon task list --cursor <n>",
   "- Bulk append/status update: trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
   "",
-  "5) Task details and description",
+  "6) Task details and description",
   "- Human list and show views default to table format.",
   "- Alternate list view: add --view compact.",
   "- task/epic/subtask list defaults: open work only (in_progress/in-progress, todo), max 10.",
@@ -53,14 +67,21 @@ const QUICKSTART_TEXT = [
   "- Full task payload (including description): trekoon --toon task show <task-id> --all",
   "- Optional integration format: trekoon --json task show <task-id> --all",
   "",
-  "6) Pre-merge sync flow",
+  "7) Pre-merge sync flow",
   "- Run: trekoon --toon sync status",
   "- Pull upstream tracker events: trekoon --toon sync pull --from main",
   "- Resolve conflicts if needed: trekoon --toon sync resolve <id> --use ours",
   "- Run sync status again before opening or merging a PR.",
   "",
-  "7) Machine output examples",
+  "8) Shared-storage wipe warning",
+  "- trekoon wipe --yes removes the shared repo-scoped .trekoon directory for every worktree in the repo.",
+  "- Treat wipe as destructive recovery, not routine cleanup.",
+  "- Never use wipe as a substitute for sync, bootstrap, or gitignore fixes.",
+  "",
+  "9) Machine output examples",
   "- trekoon --toon quickstart",
+  "- trekoon --toon session",
+  "- trekoon --toon task done <task-id> --append \"Completed implementation\"",
   "- trekoon --toon task show <task-id> --all",
   "- trekoon --toon epic show <epic-id> --all",
   "- trekoon --toon sync status",
@@ -77,17 +98,24 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       localModel: {
         storageDir: ".trekoon",
         databaseFile: ".trekoon/trekoon.db",
+        storageScope: "repo-shared-across-worktrees",
+        gitPolicy: "gitignored-operational-state",
         mergeBehavior: "manual-sync",
       },
       alignedSkill: ".agents/skills/trekoon/SKILL.md",
       requiresToonForAgents: true,
-      agentStartupChecklist: [
+      bootstrapChecklist: [
+        "trekoon --toon session",
+        "Replaces: init + sync status + task next + dep list + task show in one call",
+        "Fail fast on recoveryRequired or tracked/ignored mismatch diagnostics",
+        "Confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root",
+      ],
+      bootstrapLegacy: [
         "trekoon --toon init",
         "trekoon --toon sync status",
-        "trekoon --toon epic list",
-        "trekoon --toon task list",
-        "trekoon --toon task ready --limit 5",
-        "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon task next",
+        "trekoon --toon dep list <task-id>",
+        "trekoon --toon task show <task-id> --all",
       ],
       preMergeFlow: [
         "trekoon --toon sync status",
@@ -96,11 +124,22 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon sync status",
       ],
       executionLoop: [
-        "trekoon --toon sync status",
-        "trekoon --toon task ready --limit 5",
-        "trekoon --toon task next",
-        "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon session",
         "trekoon --toon task update <task-id> --status in_progress",
+        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
+      ],
+      diagnostics: [
+        "storageMode",
+        "repoCommonDir",
+        "worktreeRoot",
+        "sharedStorageRoot",
+        "databaseFile",
+        "recoveryRequired",
+      ],
+      recoveryGuidance: [
+        "Run trekoon --toon init to bootstrap or re-bootstrap shared storage",
+        "Stop when diagnostics report tracked/ignored mismatch or ambiguous recovery",
+        "Do not commit .trekoon/trekoon.db; remove the tracked DB and keep .trekoon ignored",
       ],
       powerUserCommands: [
         "trekoon --toon epic show <epic-id> --all",
@@ -113,6 +152,8 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       ],
       machineExamples: [
         "trekoon --toon quickstart",
+        "trekoon --toon session",
+        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
         "trekoon --toon task show <task-id> --all",
         "trekoon --toon epic show <epic-id> --all",
         "trekoon --toon sync status",
@@ -120,6 +161,11 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
       ],
+      wipeWarning: {
+        command: "trekoon wipe --yes",
+        scope: "repo-wide shared storage",
+        destructive: true,
+      },
     },
   });
 }

package/src/commands/session.ts

@@ -0,0 +1,223 @@
+import type { Database } from "bun:sqlite";
+
+import { unexpectedFailureResult } from "./error-utils";
+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";
+
+interface SessionReadiness {
+  readonly readyCount: number;
+  readonly blockedCount: number;
+}
+
+interface NextCandidate {
+  readonly id: string;
+  readonly epicId: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: string;
+  readonly subtasks: ReadonlyArray<{
+    readonly id: string;
+    readonly taskId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly status: string;
+  }>;
+}
+
+interface SessionResult {
+  readonly diagnostics: {
+    readonly storageMode: string;
+    readonly recoveryRequired: boolean;
+    readonly recoveryStatus: string;
+  };
+  readonly sync: {
+    readonly ahead: number;
+    readonly behind: number;
+    readonly pendingConflicts: number;
+    readonly git: GitContextSnapshot;
+  };
+  readonly next: NextCandidate | null;
+  readonly nextDeps: ReadonlyArray<DependencyBlocker>;
+  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[] = [];
+
+  lines.push("=== Session ===");
+  lines.push(`Storage mode: ${result.diagnostics.storageMode}`);
+  lines.push(`Recovery required: ${result.diagnostics.recoveryRequired}`);
+  lines.push(`Recovery status: ${result.diagnostics.recoveryStatus}`);
+
+  lines.push("");
+  lines.push("=== Sync ===");
+  lines.push(`Source branch: ${DEFAULT_SOURCE_BRANCH}`);
+  lines.push(`Ahead: ${result.sync.ahead}`);
+  lines.push(`Behind: ${result.sync.behind}`);
+  lines.push(`Pending conflicts: ${result.sync.pendingConflicts}`);
+  lines.push(`Branch: ${result.sync.git.branchName ?? "(detached)"}`);
+
+  lines.push("");
+  lines.push("=== Readiness ===");
+  lines.push(`Ready: ${result.readiness.readyCount}`);
+  lines.push(`Blocked: ${result.readiness.blockedCount}`);
+
+  lines.push("");
+  lines.push("=== Next Task ===");
+  if (result.next === null) {
+    lines.push("No ready tasks.");
+  } else {
+    lines.push(`${result.next.id} | epic=${result.next.epicId} | ${result.next.title} | ${result.next.status}`);
+    lines.push(`Description: ${result.next.description}`);
+    if (result.next.subtasks.length > 0) {
+      lines.push("Subtasks:");
+      for (const subtask of result.next.subtasks) {
+        lines.push(`  ${subtask.id} | ${subtask.title} | ${subtask.status}`);
+      }
+    } else {
+      lines.push("Subtasks: none");
+    }
+  }
+
+  lines.push("");
+  lines.push("=== Next Task Deps ===");
+  if (result.nextDeps.length === 0) {
+    lines.push("No blockers.");
+  } else {
+    for (const dep of result.nextDeps) {
+      lines.push(`${dep.id} | kind=${dep.kind} | status=${dep.status}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export async function runSession(context: CliContext): Promise<CliResult> {
+  let database: TrekoonDatabase | undefined;
+
+  try {
+    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 topCandidate = readiness.candidates[0] ?? null;
+
+    let nextTask: NextCandidate | null = null;
+    if (topCandidate !== null) {
+      const tree = domain.buildTaskTreeDetailed(topCandidate.task.id);
+      nextTask = tree;
+    }
+
+    const result: SessionResult = {
+      diagnostics: {
+        storageMode: diagnostics.storageMode,
+        recoveryRequired: diagnostics.recoveryRequired,
+        recoveryStatus: diagnostics.recoveryStatus,
+      },
+      sync: {
+        ahead: syncSummary.ahead,
+        behind: syncSummary.behind,
+        pendingConflicts: syncSummary.pendingConflicts,
+        git: syncSummary.git,
+      },
+      next: nextTask,
+      nextDeps: topCandidate?.blockerSummary.blockedBy ?? [],
+      readiness: {
+        readyCount: readiness.summary.readyCount,
+        blockedCount: readiness.summary.blockedCount,
+      },
+    };
+
+    return okResult({
+      command: "session",
+      human: formatSessionHuman(result),
+      data: result,
+    });
+  } catch (error: unknown) {
+    return unexpectedFailureResult(error, {
+      command: "session",
+      human: "Unexpected session command failure",
+    });
+  } finally {
+    database?.close();
+  }
+}

package/src/commands/skills.ts

@@ -16,8 +16,6 @@ const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
 const ALLOW_OUTSIDE_REPO_FLAG = "allow-outside-repo";
 
 type EditorName = (typeof EDITOR_NAMES)[number];
-type LinkStateStatus = "missing" | "valid" | "conflict";
-
 interface InstallOutcome {
   readonly sourcePath: string;
   readonly installedPath: string;
@@ -32,20 +30,22 @@ interface LinkTargetValidation {
   readonly outsideRepoLink: boolean;
 }
 
-interface LinkState {
+type UpdateLinkAction = "created" | "refreshed" | "skipped_conflict" | "skipped_no_editor_dir";
+
+interface UpdateLinkEntry {
   readonly editor: EditorName;
   readonly linkPath: string;
   readonly expectedTarget: string;
-  readonly status: LinkStateStatus;
-  readonly existingTarget: string | null;
+  readonly action: UpdateLinkAction;
   readonly conflictCode: "non_link" | "wrong_target" | null;
+  readonly existingTarget: string | null;
 }
 
 interface UpdateOutcome {
   readonly sourcePath: string;
   readonly installedPath: string;
   readonly installedDir: string;
-  readonly links: readonly LinkState[];
+  readonly links: readonly UpdateLinkEntry[];
 }
 
 function invalidArgs(message: string): CliResult {
@@ -215,6 +215,18 @@ function resolveDefaultLinkPath(cwd: string, editor: EditorName): string {
   return join(resolveLinkRoot(cwd, editor, undefined), "trekoon");
 }
 
+function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
+  if (editor === "opencode") {
+    return join(cwd, ".opencode");
+  }
+
+  if (editor === "claude") {
+    return join(cwd, ".claude");
+  }
+
+  return join(cwd, ".pi");
+}
+
 function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; installedPath: string; installedDir: string } {
   const sourcePath: string = resolveBundledSkillFilePath();
   if (!existsSync(sourcePath)) {
@@ -323,56 +335,6 @@ function replaceOrCreateSymlink(
   return null;
 }
 
-function inspectDefaultLink(cwd: string, editor: EditorName, installedDir: string): LinkState {
-  const linkPath: string = resolveDefaultLinkPath(cwd, editor);
-  const expectedTarget: string = resolve(installedDir);
-
-  if (!existsSync(linkPath)) {
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      status: "missing",
-      existingTarget: null,
-      conflictCode: null,
-    };
-  }
-
-  const entry = lstatSync(linkPath);
-  if (!entry.isSymbolicLink()) {
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      status: "conflict",
-      existingTarget: null,
-      conflictCode: "non_link",
-    };
-  }
-
-  const existingRawTarget: string = readlinkSync(linkPath);
-  const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
-  if (existingTarget !== expectedTarget) {
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      status: "conflict",
-      existingTarget,
-      conflictCode: "wrong_target",
-    };
-  }
-
-  return {
-    editor,
-    linkPath,
-    expectedTarget,
-    status: "valid",
-    existingTarget,
-    conflictCode: null,
-  };
-}
-
 function runSkillsInstall(context: CliContext): CliResult {
   const parsed = parseArgs(context.args);
   const missingValue = readMissingOptionValue(parsed.missingOptionValues, "editor", "to");
@@ -520,6 +482,77 @@ function runSkillsInstall(context: CliContext): CliResult {
   });
 }
 
+function updateEditorLink(
+  cwd: string,
+  editor: EditorName,
+  installedDir: string,
+): UpdateLinkEntry {
+  const linkPath: string = resolveDefaultLinkPath(cwd, editor);
+  const expectedTarget: string = resolve(installedDir);
+  const editorConfigDir: string = resolveEditorConfigDir(cwd, editor);
+
+  if (!existsSync(editorConfigDir)) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      action: "skipped_no_editor_dir",
+      conflictCode: null,
+      existingTarget: null,
+    };
+  }
+
+  if (!existsSync(linkPath)) {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(expectedTarget, linkPath, "dir");
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      action: "created",
+      conflictCode: null,
+      existingTarget: null,
+    };
+  }
+
+  const entry = lstatSync(linkPath);
+  if (!entry.isSymbolicLink()) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      action: "skipped_conflict",
+      conflictCode: "non_link",
+      existingTarget: null,
+    };
+  }
+
+  const existingRawTarget: string = readlinkSync(linkPath);
+  const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+
+  if (existingTarget !== expectedTarget) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      action: "skipped_conflict",
+      conflictCode: "wrong_target",
+      existingTarget,
+    };
+  }
+
+  rmSync(linkPath, { force: true });
+  symlinkSync(expectedTarget, linkPath, "dir");
+  return {
+    editor,
+    linkPath,
+    expectedTarget,
+    action: "refreshed",
+    conflictCode: null,
+    existingTarget,
+  };
+}
+
 function runSkillsUpdate(context: CliContext): CliResult {
   const parsed = parseArgs(context.args);
   if (parsed.positional.length > 1) {
@@ -544,8 +577,8 @@ function runSkillsUpdate(context: CliContext): CliResult {
     });
   }
 
-  const links: readonly LinkState[] = EDITOR_NAMES.map((editor) =>
-    inspectDefaultLink(context.cwd, editor, installResult.installedDir),
+  const links: readonly UpdateLinkEntry[] = EDITOR_NAMES.map((editor) =>
+    updateEditorLink(context.cwd, editor, installResult.installedDir),
   );
 
   const outcome: UpdateOutcome = {
@@ -557,12 +590,16 @@ function runSkillsUpdate(context: CliContext): CliResult {
 
   const linkSummary: string = outcome.links
     .map((entry) => {
-      if (entry.status === "missing") {
-        return `- ${entry.editor}: missing (${entry.linkPath})`;
+      if (entry.action === "created") {
+        return `- ${entry.editor}: created (${entry.linkPath} -> ${entry.expectedTarget})`;
+      }
+
+      if (entry.action === "refreshed") {
+        return `- ${entry.editor}: refreshed (${entry.linkPath} -> ${entry.expectedTarget})`;
       }
 
-      if (entry.status === "valid") {
-        return `- ${entry.editor}: valid (${entry.linkPath} -> ${entry.expectedTarget})`;
+      if (entry.action === "skipped_no_editor_dir") {
+        return `- ${entry.editor}: skipped (no editor config dir)`;
       }
 
       if (entry.conflictCode === "non_link") {
@@ -579,7 +616,7 @@ function runSkillsUpdate(context: CliContext): CliResult {
       "Updated Trekoon skill in canonical path.",
       `Source: ${outcome.sourcePath}`,
       `Installed file: ${outcome.installedPath}`,
-      "Default link states:",
+      "Editor links:",
       linkSummary,
     ].join("\n"),
     data: {