trekoon 0.1.7 → 0.1.8

package/src/commands/help.ts

@@ -1,8 +1,10 @@
 import { okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { CLI_VERSION } from "../runtime/version";
 
 const ROOT_HELP = [
   "Trekoon - AI-first local issue tracker",
+  `Version: ${CLI_VERSION}`,
   "",
   "Usage:",
   "  trekoon [global-options] <command> [command-options]",
@@ -15,7 +17,7 @@ const ROOT_HELP = [
   "",
   "Commands:",
   "  init         Initialize .trekoon storage and local DB",
-  "  quickstart   Show workflow + where to see task descriptions",
+  "  quickstart   Show AI execution loop + task detail workflow",
   "  wipe         Remove local Trekoon state (requires --yes)",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
@@ -24,25 +26,260 @@ const ROOT_HELP = [
   "  events       Event retention and cleanup commands",
   "  migrate      Migration status and rollback commands",
   "  sync         Cross-branch sync commands",
-  "  skills       Project-local skill install/link commands",
+  "  skills       Project-local skill install/update/link",
+].join("\n");
+
+const INIT_HELP = [
+  "Usage: trekoon init [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Initialize local Trekoon storage (.trekoon) and database.",
+  "",
+  "Examples:",
+  "  trekoon init",
+  "  trekoon --json init",
+].join("\n");
+
+const QUICKSTART_HELP = [
+  "Usage: trekoon quickstart [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Show the canonical Trekoon AI execution loop and task-detail workflow.",
+  "",
+  "Flow:",
+  "  1) trekoon --toon sync status",
+  "  2) trekoon --toon task ready --limit 5",
+  "  3) trekoon --toon task next",
+  "  4) trekoon --toon dep reverse <task-or-subtask-id>",
+  "  5) trekoon --toon task update <task-id> --status in_progress",
+  "",
+  "Examples:",
+  "  trekoon quickstart",
+  "  trekoon --toon quickstart",
+].join("\n");
+
+const WIPE_HELP = [
+  "Usage: trekoon wipe --yes [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Remove local Trekoon state for the current repository.",
+  "",
+  "Options:",
+  "  --yes  Required safety confirmation.",
+  "",
+  "Examples:",
+  "  trekoon wipe --yes",
+].join("\n");
+
+const EPIC_HELP = [
+  "Usage: trekoon epic <create|list|show|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Show behavior:",
+  "  Views:",
+  "    - compact: epic summary",
+  "    - tree: hierarchy",
+  "    - detail: descriptions",
+  "  Machine default:",
+  "    - With --all, machine modes default to detail",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const TASK_HELP = [
+  "Usage: trekoon task <create|list|show|ready|next|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Show behavior:",
+  "  Views:",
+  "    - compact: task summary",
+  "    - tree: hierarchy",
+  "    - detail: descriptions",
+  "  Machine default:",
+  "    - With --all, machine modes default to detail",
+  "",
+  "Ready/Next behavior:",
+  "  ready:",
+  "    - Returns deterministic unblocked candidates",
+  "    - Sort order: status, blockers, createdAt, id",
+  "    - Options: --limit <n>, --epic <id>",
+  "  next:",
+  "    - Returns top ready candidate",
+  "    - Option: --epic <id>",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const SUBTASK_HELP = [
+  "Usage: trekoon subtask <create|list|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --task <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const DEP_HELP = [
+  "Usage: trekoon dep <add|remove|list|reverse> [options]",
+  "",
+  "Subcommands:",
+  "  add <source-id> <depends-on-id>",
+  "      Create dependency edge: source depends on depends-on.",
+  "  remove <source-id> <depends-on-id>",
+  "      Remove one dependency edge if it exists.",
+  "  list <source-id>",
+  "      Show direct dependencies for a node.",
+  "  reverse <target-id>",
+  "      Show downstream nodes blocked by target (with distance).",
+  "",
+  "Examples:",
+  "  trekoon dep add <task-a> <task-b>",
+  "  trekoon dep remove <task-a> <task-b>",
+  "  trekoon dep list <task-a>",
+  "  trekoon dep reverse <task-b>",
+].join("\n");
+
+const EVENTS_HELP = [
+  "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
+  "",
+  "Purpose:",
+  "  Manage retention for internal sync event log rows.",
+  "",
+  "Options:",
+  "  --dry-run             Preview candidate/archive/delete counts only.",
+  "  --archive             Copy pruned rows to event_archive before delete.",
+  "  --retention-days <n>  Keep last n days (positive integer, default 90).",
+  "",
+  "Examples:",
+  "  trekoon events prune --dry-run",
+  "  trekoon events prune --retention-days 30",
+  "  trekoon events prune --archive",
+].join("\n");
+
+const MIGRATE_HELP = [
+  "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
+  "",
+  "Subcommands:",
+  "  status",
+  "      Show current schema version, latest version, and pending count.",
+  "  rollback [--to-version <n>]",
+  "      Roll back migrations; default target is one version back.",
+  "",
+  "Examples:",
+  "  trekoon migrate status",
+  "  trekoon migrate rollback",
+  "  trekoon migrate rollback --to-version 1",
+].join("\n");
+
+const SYNC_HELP = [
+  "Usage: trekoon sync <status|pull|resolve|conflicts> [options]",
+  "",
+  "Subcommands:",
+  "  status [--from <branch>]",
+  "      Show ahead/behind counts and pending conflicts vs source branch (default: main).",
+  "  pull --from <branch>",
+  "      Pull and apply upstream tracker events from a source branch.",
+  "  conflicts list [--mode pending|all]",
+  "      List sync conflicts (default mode: pending).",
+  "  conflicts show <conflict-id>",
+  "      Show full details for one conflict.",
+  "  resolve <conflict-id> --use ours|theirs",
+  "      Resolve a pending conflict by selecting ours or theirs.",
+  "",
+  "Examples:",
+  "  trekoon sync status",
+  "  trekoon sync status --from main",
+  "  trekoon sync pull --from main",
+  "  trekoon sync conflicts list",
+  "  trekoon sync conflicts list --mode all",
+  "  trekoon sync conflicts show <conflict-id>",
+  "  trekoon sync resolve <conflict-id> --use ours",
+].join("\n");
+
+const SKILLS_HELP = [
+  "Usage:",
+  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills update",
+  "",
+  "Purpose:",
+  "  Install or refresh the project-local Trekoon skill asset.",
+  "",
+  "Install behavior:",
+  "  - Always installs canonical file to:",
+  "      <cwd>/.agents/skills/trekoon/SKILL.md",
+  "  - Use --link to also create an editor symlink named 'trekoon'.",
+  "  - --editor is required when --link is used (opencode|claude|pi).",
+  "  - --to overrides the symlink root for --link only.",
+  "  - Without --allow-outside-repo, link targets must resolve inside repo.",
+  "  - --allow-outside-repo requires --link and disables that boundary check.",
+  "",
+  "Update behavior:",
+  "  - Refreshes canonical SKILL file in the install path above.",
+  "  - Reports default link states for opencode/claude/pi.",
+  "",
+  "Examples:",
+  "  trekoon skills install",
+  "  trekoon skills install --link --editor opencode",
+  "  trekoon skills install --link --editor claude --to .claude/skills",
+  "  trekoon skills install --link --editor pi --to ../shared/skills --allow-outside-repo",
+  "  trekoon skills update",
 ].join("\n");
 
 const COMMAND_HELP: Record<string, string> = {
-  init: "Usage: trekoon init [--json|--toon]",
-  quickstart: "Usage: trekoon quickstart [--json|--toon]",
-  wipe: "Usage: trekoon wipe --yes [--json|--toon]",
-  epic:
-    "Usage: trekoon epic <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=epic summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  task:
-    "Usage: trekoon task <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=task summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  subtask:
-    "Usage: trekoon subtask <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --task <id> | --status <csv> | --limit <n> | --all | --view table|compact; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  dep: "Usage: trekoon dep <subcommand> [options]",
-  events: "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
-  migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
-  sync: "Usage: trekoon sync <subcommand> [options]",
-  skills:
-    "Usage: trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo] | trekoon skills update (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md; links must resolve inside repo unless --allow-outside-repo is set; update refreshes canonical SKILL and reports default link states)",
+  init: INIT_HELP,
+  quickstart: QUICKSTART_HELP,
+  wipe: WIPE_HELP,
+  epic: EPIC_HELP,
+  task: TASK_HELP,
+  subtask: SUBTASK_HELP,
+  dep: DEP_HELP,
+  events: EVENTS_HELP,
+  migrate: MIGRATE_HELP,
+  sync: SYNC_HELP,
+  skills: SKILLS_HELP,
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 
@@ -64,6 +301,7 @@ export async function runHelp(context: CliContext): Promise<CliResult> {
     data: {
       topic,
       text,
+      version: CLI_VERSION,
     },
   });
 }

package/src/commands/quickstart.ts

@@ -4,34 +4,69 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 const QUICKSTART_TEXT = [
   "Trekoon quickstart",
   "",
+  "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.",
   "",
-  "2) Pre-merge sync flow",
-  "- Run: trekoon sync status",
-  "- Pull upstream tracker events: trekoon sync pull --from main",
-  "- Resolve conflicts if needed: trekoon sync resolve <id> --use ours",
-  "- Run sync status again before opening or merging a PR.",
+  "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>",
+  "",
+  "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",
   "",
-  "3) Task details and description",
+  "4) 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>",
+  "- Find what this item unblocks: trekoon --toon dep reverse <task-or-subtask-id>",
+  "- Filter list explicitly: trekoon --toon task list --status in_progress,todo --limit 20",
+  "- 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",
   "- 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.",
   "- Filter list by status: --status in_progress,todo (CSV).",
   "- Change page size: --limit <n>. Show all statuses and all rows with --all.",
-  "- --all cannot be combined with --status or --limit.",
+  "- Continue pagination with --cursor <n> (offset-like list position).",
+  "- --all cannot be combined with --status, --limit, or --cursor.",
   "- Bulk update: use --all or --ids <csv> with --append and/or --status.",
   "- Bulk update rejects positional id, and --all/--ids cannot be combined.",
-  "- Full tree + descriptions: trekoon epic show <epic-id> --all --json",
-  "- For full task payload (including description), use --json:",
-  "  trekoon task show <task-id> --all --json",
-  "",
-  "4) Machine output examples",
-  "- trekoon quickstart --json",
-  "- trekoon task show <task-id> --all --json",
-  "- trekoon epic show <epic-id> --all --json",
-  "- trekoon sync status --toon",
+  "- Ready queue: trekoon task ready [--limit <n>] [--epic <id>] (deterministic order).",
+  "- Next execution candidate: trekoon task next [--epic <id>]",
+  "- Full tree + descriptions (canonical): trekoon --toon epic show <epic-id> --all",
+  "- 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",
+  "- 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",
+  "- trekoon --toon quickstart",
+  "- trekoon --toon task show <task-id> --all",
+  "- trekoon --toon epic show <epic-id> --all",
+  "- trekoon --toon sync status",
+  "- trekoon --toon task ready --limit 5",
+  "- trekoon --toon task next",
+  "- trekoon --toon dep reverse <task-or-subtask-id>",
 ].join("\n");
 
 export async function runQuickstart(_: CliContext): Promise<CliResult> {
@@ -44,17 +79,46 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         databaseFile: ".trekoon/trekoon.db",
         mergeBehavior: "manual-sync",
       },
+      alignedSkill: ".agents/skills/trekoon/SKILL.md",
+      requiresToonForAgents: true,
+      agentStartupChecklist: [
+        "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>",
+      ],
       preMergeFlow: [
-        "trekoon sync status",
-        "trekoon sync pull --from main",
-        "trekoon sync resolve <id> --use ours",
-        "trekoon sync status",
+        "trekoon --toon sync status",
+        "trekoon --toon sync pull --from main",
+        "trekoon --toon sync resolve <id> --use ours",
+        "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 task update <task-id> --status in_progress",
+      ],
+      powerUserCommands: [
+        "trekoon --toon epic show <epic-id> --all",
+        "trekoon --toon task show <task-id> --all",
+        "trekoon --toon dep list <task-id>",
+        "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon task list --status in_progress,todo --limit 20",
+        "trekoon --toon task list --cursor <n>",
+        "trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
       ],
       machineExamples: [
-        "trekoon quickstart --json",
-        "trekoon task show <task-id> --all --json",
-        "trekoon epic show <epic-id> --all --json",
-        "trekoon sync status --toon",
+        "trekoon --toon quickstart",
+        "trekoon --toon task show <task-id> --all",
+        "trekoon --toon epic show <epic-id> --all",
+        "trekoon --toon sync status",
+        "trekoon --toon task ready --limit 5",
+        "trekoon --toon task next",
+        "trekoon --toon dep reverse <task-or-subtask-id>",
       ],
     },
   });

package/src/commands/subtask.ts

@@ -1,4 +1,12 @@
-import { hasFlag, parseArgs, parseStrictPositiveInt, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import {
+  hasFlag,
+  parseArgs,
+  parseStrictNonNegativeInt,
+  parseStrictPositiveInt,
+  readEnumOption,
+  readMissingOptionValue,
+  readOption,
+} from "./arg-parser";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -54,16 +62,44 @@ function filterSortAndLimitSubtasks(
   subtasks: readonly SubtaskRecord[],
   statuses: readonly string[] | undefined,
   limit: number | undefined,
-): SubtaskRecord[] {
+  cursor: number,
+): { subtasks: SubtaskRecord[]; pagination: { hasMore: boolean; nextCursor: string | null } } {
   const allowedStatuses = statuses === undefined ? undefined : new Set(statuses);
   const filtered = allowedStatuses === undefined ? [...subtasks] : subtasks.filter((subtask) => allowedStatuses.has(subtask.status));
-  const sorted = [...filtered].sort((left, right) => subtaskStatusPriority(left.status) - subtaskStatusPriority(right.status));
+  const sorted = [...filtered].sort((left, right) => {
+    const byStatus = subtaskStatusPriority(left.status) - subtaskStatusPriority(right.status);
+    if (byStatus !== 0) {
+      return byStatus;
+    }
+
+    const byCreatedAt = left.createdAt - right.createdAt;
+    if (byCreatedAt !== 0) {
+      return byCreatedAt;
+    }
+
+    return left.id.localeCompare(right.id);
+  });
 
   if (limit === undefined) {
-    return sorted;
+    return {
+      subtasks: sorted,
+      pagination: {
+        hasMore: false,
+        nextCursor: null,
+      },
+    };
   }
 
-  return sorted.slice(0, limit);
+  const pagedSubtasks = sorted.slice(cursor, cursor + limit);
+  const nextIndex = cursor + pagedSubtasks.length;
+  const hasMore = nextIndex < sorted.length;
+  return {
+    subtasks: pagedSubtasks,
+    pagination: {
+      hasMore,
+      nextCursor: hasMore ? `${nextIndex}` : null,
+    },
+  };
 }
 
 function appendLine(existing: string, line: string): string {
@@ -161,6 +197,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
+          readMissingOptionValue(parsed.missingOptionValues, "cursor") ??
           readMissingOptionValue(parsed.missingOptionValues, "task", "t");
         if (missingListOption !== undefined) {
           return failMissingOptionValue("subtask.list", missingListOption);
@@ -171,6 +208,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         const includeAll = hasFlag(parsed.flags, "all");
         const rawStatuses = readOption(parsed.options, "status", "s");
         const rawLimit = readOption(parsed.options, "limit", "l");
+        const rawCursor = readOption(parsed.options, "cursor");
 
         if (rawView !== undefined && view === undefined) {
           return failResult({
@@ -208,6 +246,18 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
+        if (includeAll && rawCursor !== undefined) {
+          return failResult({
+            command: "subtask.list",
+            human: "Use either --all or --cursor, not both.",
+            data: { code: "invalid_input", flags: ["all", "cursor"] },
+            error: {
+              code: "invalid_input",
+              message: "--all and --cursor are mutually exclusive",
+            },
+          });
+        }
+
         const statuses = parseStatusCsv(rawStatuses);
         if (rawStatuses !== undefined && statuses !== undefined && statuses.length === 0) {
           return failResult({
@@ -234,6 +284,19 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
+        const parsedCursor = parseStrictNonNegativeInt(rawCursor);
+        if (Number.isNaN(parsedCursor)) {
+          return failResult({
+            command: "subtask.list",
+            human: "Invalid --cursor value. Use an integer >= 0.",
+            data: { code: "invalid_input", cursor: rawCursor },
+            error: {
+              code: "invalid_input",
+              message: "Invalid --cursor value",
+            },
+          });
+        }
+
         const taskId: string | undefined = readOption(parsed.options, "task", "t") ?? parsed.positional[1];
         const selectedStatuses = includeAll
           ? undefined
@@ -241,7 +304,13 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         const selectedLimit = includeAll
           ? undefined
           : parsedLimit ?? DEFAULT_SUBTASK_LIST_LIMIT;
-        const subtasks = filterSortAndLimitSubtasks(domain.listSubtasks(taskId), selectedStatuses, selectedLimit);
+        const listed = filterSortAndLimitSubtasks(
+          domain.listSubtasks(taskId),
+          selectedStatuses,
+          selectedLimit,
+          parsedCursor ?? 0,
+        );
+        const subtasks = listed.subtasks;
         const listView = view ?? "table";
         const human =
           subtasks.length === 0
@@ -254,6 +323,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           command: "subtask.list",
           human,
           data: { subtasks },
+          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
         });
       }
       case "update": {