opentasks 0.1.3 → 0.2.0

package/dist/cli.js

@@ -8,6 +8,8 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { generateLocationIdentity } from './core/location.js';
 import { ensureGlobalStoreInitialized } from './core/init.js';
 import { createConnection, checkAllConnectionHealth } from './core/connections.js';
@@ -16,17 +18,24 @@ import { mergeJsonl, installMergeDriver } from './core/merge-driver.js';
 import { discoverLocations } from './core/discover.js';
 import { OpenTasksClient } from './client/client.js';
 import { createDaemonWithStore, createMultiLocationDaemonFromGit, checkExistingDaemon } from './daemon/index.js';
+import { VERSION } from './version.js';
 const OPENTASKS_DIR = '.opentasks';
+const OPENSWARM_OPENTASKS_DIR = '.openswarm/opentasks';
 const SWARM_OPENTASKS_DIR = '.swarm/opentasks';
 const CONFIG_FILE = 'config.json';
 /**
  * Resolve the project-level opentasks directory.
- * Priority: OPENTASKS_PROJECT_DIR env var > .swarm/opentasks > .opentasks
+ * Priority: OPENTASKS_PROJECT_DIR env > .openswarm/opentasks > .swarm/opentasks
+ * (legacy) > .opentasks. The swarmkit namespace is migrating .swarm → .openswarm;
+ * both are honored so mixed-version repos keep working, preferring the new name.
  */
 function resolveProjectDir(baseDir = process.cwd()) {
     const envDir = process.env.OPENTASKS_PROJECT_DIR;
     if (envDir)
         return path.resolve(baseDir, envDir);
+    const openswarmDir = path.resolve(baseDir, OPENSWARM_OPENTASKS_DIR);
+    if (fs.existsSync(openswarmDir))
+        return openswarmDir;
     const swarmDir = path.resolve(baseDir, SWARM_OPENTASKS_DIR);
     if (fs.existsSync(swarmDir))
         return swarmDir;
@@ -34,12 +43,12 @@ function resolveProjectDir(baseDir = process.cwd()) {
 }
 function printHelp() {
     console.log(`
-opentasks v0.1.0
+opentasks v${VERSION}
 
 Usage:
   opentasks <command> [options]
 
-Tool commands (require running daemon):
+Tool commands (auto-start the daemon if needed; --no-autostart to opt out):
   link    --from <id> --to <id> --type <type> [--remove] [--metadata <json>]
   query   <json>                Query the graph (pass QueryParams as JSON)
   annotate <json>               Manage feedback (pass AnnotateParams as JSON)
@@ -48,9 +57,20 @@ Tool commands (require running daemon):
   update  <id> [options]        Update a node
   delete  <id> [--hard]         Delete a node
   context-summary [options]     Get context summary breadcrumbs for session continuity
+  claim   <id> --agent <id> [--duration <ms>] [--force]      Atomically claim a task (lease)
+  claim-next --agent <id> [--duration <ms>]                  Claim the next ready, unclaimed task
+  release <id> --agent <id> [--fence <n>]                    Release a claim
+  renew   <id> --agent <id> [--duration <ms>] [--fence <n>]  Renew/extend a claim's lease
+
+Views (compact, human-readable; --json for raw, --limit <n>, default ${DEFAULT_LIST_LIMIT}):
+  ready   [--tags a,b]           Unblocked tasks ready to work on
+  list    [--type <t>] [--status <s>] [--tags a,b] [--all]   Tasks (closed hidden unless --all)
+  blocked                        Open tasks waiting on an unresolved blocker
+  tree    <id>                   A task and its blocker dependency tree
+  cleanup [--older-than-days <n>] [--dry-run]   Archive terminal tasks older than n days (default 30)
 
 Create options:
-  --status <s>                  Status (required for tasks)
+  --status <s>                  Status (default: open for tasks)
   --content <text>              Markdown content
   --uri <uri>                   External URI (for external nodes)
   --source <src>                Source system (for external nodes)
@@ -87,6 +107,11 @@ Setup commands:
   discover [options]            Find nearby opentasks locations
   merge-driver <O> <A> <B>     JSONL merge driver (for git)
 
+Global options (any command):
+  --global                      Target the shared store at ~/.opentasks (use from
+                                anywhere; same as OPENTASKS_GLOBAL=1)
+  --no-autostart                Don't auto-start a daemon (OPENTASKS_NO_AUTOSTART=1)
+
 Archive commands (require running daemon with archival enabled):
   archive list [--graph <id>] [--source <src>]   List archived sessions
   archive restore <uri>                          Restore a node from archive
@@ -133,7 +158,9 @@ function writeConfig(opentasksDir, config) {
 function cmdInit(args) {
     const nameIndex = args.indexOf('--name');
     const name = nameIndex !== -1 ? args[nameIndex + 1] : undefined;
-    const isGlobal = args.includes('--global');
+    // `--global` is stripped + routed via OPENTASKS_PROJECT_DIR in main(); detect
+    // it from the resolved target dir so the global init message still fires.
+    const isGlobal = resolveProjectDir() === path.join(os.homedir(), '.opentasks');
     // Global init delegates to the shared utility
     if (isGlobal) {
         ensureGlobalStoreInitialized(name ?? 'global');
@@ -443,12 +470,87 @@ function cmdDiscover(args) {
 // ============================================================================
 // Daemon Commands
 // ============================================================================
+/** Resolve the path to this CLI entrypoint (dist/cli.js) for re-spawning. */
+function cliEntrypoint() {
+    return fileURLToPath(import.meta.url);
+}
+/**
+ * Resolve the directory the daemon actually uses for its lock + socket.
+ *
+ * In a git repo the daemon runs in multi-location mode with its home at
+ * `<git-common-dir>/opentasks` (shared across worktrees); otherwise it's the
+ * location's own `.opentasks`. This must match `cmdDaemonStart`'s single-vs-multi
+ * decision, or the CLI's `checkExistingDaemon` probes look in the wrong place and
+ * never detect a running git-repo daemon (auto-start "times out", `daemon status`
+ * reports not_running, `daemon stop` no-ops — even though the daemon is up).
+ */
+export function daemonHomeFor(opentasksDir) {
+    const gitCommonDir = getGitCommonDir(path.dirname(opentasksDir));
+    return gitCommonDir ? path.join(gitCommonDir, 'opentasks') : opentasksDir;
+}
+/**
+ * Spawn a detached daemon process (`daemon start --foreground`) and let it
+ * outlive this process. The child inherits cwd + env so it resolves the same
+ * project as the parent.
+ */
+function spawnDetachedDaemon() {
+    const child = spawn(process.execPath, [cliEntrypoint(), 'daemon', 'start', '--foreground'], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+}
+/** Sleep helper for poll loops. */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Poll until the daemon for `opentasksDir` reports running, or throw on timeout.
+ */
+async function waitForDaemon(opentasksDir, timeoutMs = 10_000) {
+    const daemonHome = daemonHomeFor(opentasksDir);
+    const start = Date.now();
+    for (;;) {
+        const existing = await checkExistingDaemon(daemonHome);
+        if (existing.running)
+            return;
+        if (Date.now() - start >= timeoutMs) {
+            throw new Error(`Daemon did not start within ${timeoutMs}ms`);
+        }
+        await delay(100);
+    }
+}
+/**
+ * Ensure a daemon is running for `opentasksDir`, auto-starting one if needed
+ * (4.1). Auto-start is on by default; opt out with `--no-autostart` or
+ * `OPENTASKS_NO_AUTOSTART=1`. When auto-start is disabled and no daemon is
+ * running, this is a no-op — the subsequent client connect surfaces a clear
+ * "not connected" error.
+ */
+async function ensureDaemonRunning(opentasksDir, options = { autostart: true }) {
+    const daemonHome = daemonHomeFor(opentasksDir);
+    const existing = await checkExistingDaemon(daemonHome);
+    if (existing.running)
+        return;
+    if (!options.autostart)
+        return;
+    process.stderr.write('opentasks: no daemon running — starting one…\n');
+    spawnDetachedDaemon();
+    try {
+        await waitForDaemon(opentasksDir);
+        const started = await checkExistingDaemon(daemonHome);
+        process.stderr.write(`opentasks: daemon started (pid ${started.pid ?? '?'})\n`);
+    }
+    catch (error) {
+        process.stderr.write(`opentasks: daemon auto-start failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
 /**
  * Start the daemon process.
  *
- * By default runs in the foreground (keeps the process alive).
- * The caller (e.g., claude-code-swarm's ensureDaemon) spawns this
- * as a detached subprocess.
+ * Detaches by default and returns once the daemon is accepting connections.
+ * Pass `--foreground` to run it in the foreground (used by the detached child
+ * and by callers that manage the lifecycle themselves).
  */
 async function cmdDaemonStart(args) {
     const opentasksDir = resolveProjectDir();
@@ -460,8 +562,9 @@ async function cmdDaemonStart(args) {
             fs.writeFileSync(graphPath, '', 'utf-8');
         }
     }
-    // Check if already running
-    const existing = await checkExistingDaemon(opentasksDir);
+    // Check if already running (probe the daemon's real home — .git/opentasks in a repo)
+    const daemonHome = daemonHomeFor(opentasksDir);
+    const existing = await checkExistingDaemon(daemonHome);
     if (existing.running) {
         console.log(JSON.stringify({
             status: 'already_running',
@@ -470,9 +573,24 @@ async function cmdDaemonStart(args) {
         }));
         return;
     }
+    // Detach by default (4.2): re-spawn ourselves in the foreground, wait until
+    // the daemon is accepting connections, then report and return. `--foreground`
+    // runs the blocking daemon loop in-process.
+    if (!args.includes('--foreground')) {
+        spawnDetachedDaemon();
+        await waitForDaemon(opentasksDir);
+        const started = await checkExistingDaemon(daemonHome);
+        console.log(JSON.stringify({
+            status: 'started',
+            detached: true,
+            pid: started.pid,
+            socketPath: started.socketPath,
+        }));
+        return;
+    }
     // Detect multi-location (git worktree) vs single-location mode
     const gitCommonDir = getGitCommonDir(path.dirname(opentasksDir));
-    const version = '0.0.5';
+    const version = VERSION;
     let daemon;
     if (gitCommonDir) {
         daemon = createMultiLocationDaemonFromGit({
@@ -511,7 +629,7 @@ async function cmdDaemonStart(args) {
  */
 async function cmdDaemonStop() {
     const opentasksDir = resolveProjectDir();
-    const existing = await checkExistingDaemon(opentasksDir);
+    const existing = await checkExistingDaemon(daemonHomeFor(opentasksDir));
     if (!existing.running) {
         console.log(JSON.stringify({ status: 'not_running' }));
         return;
@@ -523,7 +641,7 @@ async function cmdDaemonStop() {
         client.disconnect();
         console.log(JSON.stringify({ status: 'stopped', ...result }));
     }
-    catch (error) {
+    catch (_error) {
         client.disconnect();
         // If the connection was refused or reset, the daemon may have already stopped
         console.log(JSON.stringify({ status: 'stopped', note: 'daemon may have already exited' }));
@@ -534,7 +652,7 @@ async function cmdDaemonStop() {
  */
 async function cmdDaemonStatus() {
     const opentasksDir = resolveProjectDir();
-    const existing = await checkExistingDaemon(opentasksDir);
+    const existing = await checkExistingDaemon(daemonHomeFor(opentasksDir));
     if (!existing.running) {
         console.log(JSON.stringify({ status: 'not_running', locationPath: opentasksDir }));
         return;
@@ -582,6 +700,172 @@ async function runToolCommand(fn) {
         process.exit(1);
     }
 }
+// ============================================================================
+// Human-readable commands (token-light sugar over `query`) — P4 4.4
+// ============================================================================
+const DEFAULT_LIST_LIMIT = 50;
+const TERMINAL_STATUSES = new Set(['closed', 'failed', 'abandoned']);
+/** One compact line per task — id, status, priority, truncated title. */
+function printTaskRows(rows, total, limit) {
+    if (rows.length === 0) {
+        console.log('(none)');
+        return;
+    }
+    const shown = rows.slice(0, limit);
+    for (const r of shown) {
+        const id = (r.id ?? '').padEnd(10).slice(0, 10);
+        const status = (r.status ?? '').padEnd(11).slice(0, 11);
+        const pri = r.priority !== undefined ? `P${r.priority}` : '  ';
+        const raw = r.title ?? '';
+        const title = raw.length > 64 ? raw.slice(0, 63) + '…' : raw;
+        console.log(`${id}  ${status} ${pri}  ${title}`);
+    }
+    const omitted = total - shown.length;
+    if (omitted > 0) {
+        console.log(`… ${omitted} more (showing ${shown.length} of ${total}; use --limit / --all)`);
+    }
+}
+/** Run `fn` with a connected client; report errors as JSON; always disconnect. */
+async function withClient(fn) {
+    const client = new OpenTasksClient();
+    try {
+        await fn(client);
+    }
+    catch (error) {
+        console.error(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+        process.exitCode = 1;
+    }
+    finally {
+        client.disconnect();
+    }
+}
+export async function cmdReady(args) {
+    const limit = Number(getFlag(args, '--limit') ?? DEFAULT_LIST_LIMIT);
+    const tags = getFlag(args, '--tags')?.split(',').map((s) => s.trim());
+    const json = hasFlag(args, '--json');
+    await withClient(async (client) => {
+        const result = (await client.query({ ready: { limit, tags } }));
+        const items = result.items ?? [];
+        if (json) {
+            console.log(JSON.stringify(items, null, 2));
+            return;
+        }
+        printTaskRows(items, result.total ?? items.length, limit);
+    });
+}
+export async function cmdList(args) {
+    const type = getFlag(args, '--type');
+    const status = getFlag(args, '--status');
+    const tags = getFlag(args, '--tags')?.split(',').map((s) => s.trim());
+    const all = hasFlag(args, '--all');
+    const limit = Number(getFlag(args, '--limit') ?? DEFAULT_LIST_LIMIT);
+    const json = hasFlag(args, '--json');
+    await withClient(async (client) => {
+        const nodes = { archived: false };
+        if (type)
+            nodes.type = type;
+        if (status)
+            nodes.status = status;
+        if (tags)
+            nodes.tags = tags;
+        const result = (await client.query({ nodes }));
+        let items = result.items ?? [];
+        // Hide terminal (closed/failed/abandoned) tasks by default; --all or an
+        // explicit --status overrides.
+        if (!all && !status) {
+            items = items.filter((i) => !TERMINAL_STATUSES.has(i.status ?? ''));
+        }
+        if (json) {
+            console.log(JSON.stringify(items.slice(0, limit), null, 2));
+            return;
+        }
+        printTaskRows(items, items.length, limit);
+    });
+}
+export async function cmdBlocked(args) {
+    const limit = Number(getFlag(args, '--limit') ?? DEFAULT_LIST_LIMIT);
+    const json = hasFlag(args, '--json');
+    await withClient(async (client) => {
+        const [active, ready] = await Promise.all([
+            client.query({ nodes: { type: 'task', archived: false } }),
+            client.query({ ready: { limit: 100_000 } }),
+        ]);
+        const readyIds = new Set((ready.items ?? []).map((i) => i.id));
+        // An open/blocked task that isn't in the ready set is waiting on a blocker.
+        const blocked = (active.items ?? []).filter((i) => (i.status === 'open' || i.status === 'blocked') && !readyIds.has(i.id));
+        if (json) {
+            console.log(JSON.stringify(blocked, null, 2));
+            return;
+        }
+        printTaskRows(blocked, blocked.length, limit);
+    });
+}
+export async function cmdCleanup(args) {
+    const ttlDays = Number(getFlag(args, '--older-than-days') ?? 30);
+    const dryRun = hasFlag(args, '--dry-run');
+    const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
+    await withClient(async (client) => {
+        // Terminal, not-yet-archived tasks are the cleanup candidates.
+        const result = (await client.query({
+            nodes: { type: 'task', status: ['closed', 'failed', 'abandoned'], archived: false },
+        }));
+        const candidates = result.items ?? [];
+        // NodeSummary carries no timestamp, so fetch each candidate to check age.
+        const stale = [];
+        for (const c of candidates) {
+            const full = (await client.getNode(c.id));
+            const ts = full?.updated_at ?? full?.created_at;
+            if (ts && new Date(ts).getTime() <= cutoff) {
+                stale.push({ id: c.id, title: c.title, status: c.status, ts });
+            }
+        }
+        if (dryRun) {
+            console.log(JSON.stringify({ dryRun: true, olderThanDays: ttlDays, wouldArchive: stale.length, tasks: stale }, null, 2));
+            return;
+        }
+        for (const t of stale) {
+            await client.updateNode(t.id, { archived: true });
+        }
+        console.log(JSON.stringify({ archived: stale.length, olderThanDays: ttlDays }, null, 2));
+    });
+}
+export async function cmdTree(args) {
+    const id = args.find((a) => !a.startsWith('--'));
+    if (!id) {
+        console.error('Usage: opentasks tree <id> [--json]');
+        process.exit(1);
+    }
+    const json = hasFlag(args, '--json');
+    await withClient(async (client) => {
+        const root = (await client.getNode(id));
+        if (!root) {
+            console.error(JSON.stringify({ error: `Not found: ${id}` }));
+            process.exitCode = 1;
+            return;
+        }
+        // Walk the blocker tree (what this task depends on), depth-limited + cycle-safe.
+        const lines = [];
+        const seen = new Set();
+        async function walk(node, depth) {
+            const indent = '  '.repeat(depth);
+            const marker = depth === 0 ? '' : '↳ ';
+            lines.push(`${indent}${marker}${node.id}  [${node.status ?? '?'}]  ${node.title ?? ''}`);
+            if (seen.has(node.id) || depth >= 6)
+                return;
+            seen.add(node.id);
+            const blockers = (await client.blockers(node.id));
+            for (const b of blockers) {
+                await walk(b, depth + 1);
+            }
+        }
+        await walk(root, 0);
+        if (json) {
+            console.log(JSON.stringify({ root: id, tree: lines }, null, 2));
+            return;
+        }
+        console.log(lines.join('\n'));
+    });
+}
 export async function cmdLink(args) {
     const fromId = getFlag(args, '--from');
     const toId = getFlag(args, '--to');
@@ -634,6 +918,82 @@ export async function cmdAnnotate(args) {
         return result;
     });
 }
+export async function cmdClaim(args) {
+    const id = args[0];
+    const agentId = getFlag(args, '--agent');
+    if (!id || id.startsWith('--') || !agentId) {
+        console.error('Usage: opentasks claim <id> --agent <agentId> [--duration <ms>] [--force]');
+        process.exit(1);
+    }
+    const durationStr = getFlag(args, '--duration');
+    const claim = { id, agentId };
+    if (durationStr)
+        claim.durationMs = Number(durationStr);
+    if (hasFlag(args, '--force'))
+        claim.force = true;
+    const client = new OpenTasksClient();
+    await runToolCommand(async () => {
+        const result = await client.task({ claim });
+        client.disconnect();
+        return result;
+    });
+}
+export async function cmdClaimNext(args) {
+    const agentId = getFlag(args, '--agent');
+    if (!agentId) {
+        console.error('Usage: opentasks claim-next --agent <agentId> [--duration <ms>]');
+        process.exit(1);
+    }
+    const durationStr = getFlag(args, '--duration');
+    const claimNext = { agentId };
+    if (durationStr)
+        claimNext.durationMs = Number(durationStr);
+    const client = new OpenTasksClient();
+    await runToolCommand(async () => {
+        const result = await client.task({ claimNext });
+        client.disconnect();
+        return result;
+    });
+}
+export async function cmdRelease(args) {
+    const id = args[0];
+    const agentId = getFlag(args, '--agent');
+    if (!id || id.startsWith('--') || !agentId) {
+        console.error('Usage: opentasks release <id> --agent <agentId> [--fence <n>]');
+        process.exit(1);
+    }
+    const fenceStr = getFlag(args, '--fence');
+    const release = { id, agentId };
+    if (fenceStr)
+        release.fence = Number(fenceStr);
+    const client = new OpenTasksClient();
+    await runToolCommand(async () => {
+        const result = await client.task({ release });
+        client.disconnect();
+        return result;
+    });
+}
+export async function cmdRenew(args) {
+    const id = args[0];
+    const agentId = getFlag(args, '--agent');
+    if (!id || id.startsWith('--') || !agentId) {
+        console.error('Usage: opentasks renew <id> --agent <agentId> [--duration <ms>] [--fence <n>]');
+        process.exit(1);
+    }
+    const durationStr = getFlag(args, '--duration');
+    const fenceStr = getFlag(args, '--fence');
+    const renew = { id, agentId };
+    if (durationStr)
+        renew.durationMs = Number(durationStr);
+    if (fenceStr)
+        renew.fence = Number(fenceStr);
+    const client = new OpenTasksClient();
+    await runToolCommand(async () => {
+        const result = await client.task({ renew });
+        client.disconnect();
+        return result;
+    });
+}
 export async function cmdCreate(args) {
     const type = getFlag(args, '--type');
     const title = getFlag(args, '--title');
@@ -652,6 +1012,8 @@ export async function cmdCreate(args) {
     const metadataStr = getFlag(args, '--metadata');
     if (status)
         params.status = status;
+    else if (type === 'task')
+        params.status = 'open';
     if (content)
         params.content = content;
     if (uri)
@@ -887,6 +1249,13 @@ async function cmdMcp(args) {
             scopeStr = args[++i];
         }
     }
+    // Auto-start the project daemon so a fresh MCP session works with zero manual
+    // daemon management (4.1). Skip when an explicit `--socket` is given (the
+    // daemon is externally managed) or auto-start is disabled. Notices go to
+    // stderr so they don't corrupt the stdio JSON-RPC channel.
+    if (!socketPath && process.env.OPENTASKS_NO_AUTOSTART !== '1') {
+        await ensureDaemonRunning(resolveProjectDir(), { autostart: true });
+    }
     const { startMCPServer, ALL_SCOPES } = await import('./mcp/index.js');
     const scopes = scopeStr === 'all'
         ? [...ALL_SCOPES]
@@ -901,13 +1270,52 @@ async function cmdMcp(args) {
 function padRight(str, len) {
     return str.length >= len ? str + '  ' : str + ' '.repeat(len - str.length);
 }
+/**
+ * Commands that talk to the daemon. For these, `main` ensures a daemon is
+ * running first (auto-starting one unless opted out).
+ */
+const DAEMON_COMMANDS = new Set([
+    'link',
+    'query',
+    'annotate',
+    'create',
+    'get',
+    'update',
+    'delete',
+    'context-summary',
+    'claim',
+    'claim-next',
+    'release',
+    'renew',
+    'ready',
+    'list',
+    'tree',
+    'blocked',
+    'cleanup',
+]);
 async function main() {
-    const args = process.argv.slice(2);
+    const rawArgs = process.argv.slice(2);
+    // Global flags, stripped so per-command arg parsing isn't disturbed.
+    const autostart = !rawArgs.includes('--no-autostart') && process.env.OPENTASKS_NO_AUTOSTART !== '1';
+    const globalMode = rawArgs.includes('--global') || process.env.OPENTASKS_GLOBAL === '1';
+    const args = rawArgs.filter((a) => a !== '--no-autostart' && a !== '--global');
     const command = args[0];
     if (!command || command === 'help' || command === '--help') {
         printHelp();
         process.exit(0);
     }
+    // --global / OPENTASKS_GLOBAL: target the use-from-anywhere store at
+    // ~/.opentasks. Routing both the auto-start (resolveProjectDir) and the
+    // client's socket discovery (findOpenTasksDir) through OPENTASKS_PROJECT_DIR
+    // keeps them in agreement. ensureGlobalStoreInitialized creates the dir so the
+    // existence check downstream passes even on first use. (4.7)
+    if (globalMode) {
+        process.env.OPENTASKS_PROJECT_DIR = ensureGlobalStoreInitialized();
+    }
+    // Auto-start the daemon for commands that need it (4.1).
+    if (DAEMON_COMMANDS.has(command)) {
+        await ensureDaemonRunning(resolveProjectDir(), { autostart });
+    }
     switch (command) {
         // Tool commands (async, require daemon)
         case 'link':
@@ -934,6 +1342,34 @@ async function main() {
         case 'context-summary':
             await cmdContextSummary(args.slice(1));
             break;
+        case 'claim':
+            await cmdClaim(args.slice(1));
+            break;
+        case 'claim-next':
+            await cmdClaimNext(args.slice(1));
+            break;
+        case 'release':
+            await cmdRelease(args.slice(1));
+            break;
+        case 'renew':
+            await cmdRenew(args.slice(1));
+            break;
+        // Human-readable commands (sugar over query)
+        case 'ready':
+            await cmdReady(args.slice(1));
+            break;
+        case 'list':
+            await cmdList(args.slice(1));
+            break;
+        case 'blocked':
+            await cmdBlocked(args.slice(1));
+            break;
+        case 'tree':
+            await cmdTree(args.slice(1));
+            break;
+        case 'cleanup':
+            await cmdCleanup(args.slice(1));
+            break;
         // Setup commands (sync, no daemon needed)
         case 'init': {
             const initArgs = args.slice(1);