@axplusb/kepler 2.0.7 → 2.3.0

package/src/core/risk-tier.mjs

@@ -18,6 +18,7 @@
 
 export const TIERS = Object.freeze({
   READ:            'read',
+  SENSITIVE_READ:  'sensitive-read',
   LOCAL_EDIT:      'local-edit',
   SHELL_SAFE:      'shell-safe',
   SHELL_MEDIUM:    'shell-medium',
@@ -35,6 +36,7 @@ export const TIERS = Object.freeze({
  */
 export const BEHAVIOR = Object.freeze({
   [TIERS.READ]:            'auto',
+  [TIERS.SENSITIVE_READ]:  'prompt-explicit',
   [TIERS.LOCAL_EDIT]:      'auto-with-undo',
   [TIERS.SHELL_SAFE]:      'auto',
   [TIERS.SHELL_MEDIUM]:    'prompt-safe',
@@ -58,6 +60,15 @@ const READ_TOOLS = new Set([
   'validate_file', 'validate_structure',
 ]);
 
+const READ_PATH_KEYS = [
+  'path', 'file_path', 'file', 'target',
+  'pattern', 'glob',
+];
+
+const READ_PATH_ARRAY_KEYS = [
+  'paths', 'file_paths', 'files', 'targets', 'patterns', 'globs',
+];
+
 const LOCAL_EDIT_TOOLS = new Set([
   'edit_file', 'write_file', 'write_project',
 ]);
@@ -77,7 +88,7 @@ const SHELL_SAFE_RE = [
   // `cd` / `pushd` / `popd` only change the process working directory; if
   // chained with something dangerous, the multi-segment classifier still
   // catches the danger (`cd /x && rm -rf .` → SHELL_DANGEROUS).
-  /^\s*(cd|pushd|popd|ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|fd|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)\b/i,
+  /^\s*(cd|pushd|popd|ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|fd|sed|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)\b/i,
   // mkdir -p / touch are creation primitives but harmless in scope.
   /^\s*mkdir\s+-p\b/i,
   /^\s*touch\s/i,
@@ -111,6 +122,8 @@ const SHELL_DANGEROUS_RE = [
   /\bcurl\b.*\|\s*(sh|bash|zsh)/i,
   /\bwget\b.*\|\s*(sh|bash|zsh)/i,
   /\beval\s+["'$(]/i,
+  /\bfind\s+\/(?:\s|$)/i,
+  /\bfind\b.*\s-(?:exec|execdir|ok|okdir|delete|fprint|fprint0|fls|fprintf)\b/i,
   /\bkubectl\s+delete/i,
   /\bdocker\s+(rm|rmi|system\s+prune|volume\s+rm|network\s+rm)/i,
   /\bdrop\s+(table|database|schema)/i,
@@ -132,6 +145,8 @@ const SHELL_MEDIUM_RE = [
   /^\s*make(\s|$)/i,
   /^\s*git\s+(commit|push|pull|merge|rebase|fetch|checkout(?!\s+\.)|cherry-pick|revert|tag|stash(?!\s+drop))/i,
   /^\s*docker\s+(build|run|exec|compose|pull|push|tag)/i,
+  /^\s*sed\b.*\s-i\S*(?:\s|$)/i,
+  /^\s*sed\b.*\s--in-place(?:=|\s|$)/i,
 ];
 
 export function classifyShell(command) {
@@ -141,6 +156,8 @@ export function classifyShell(command) {
   // Dangerous wins over safe — never let a safe-looking prefix mask `&& rm -rf`.
   if (SHELL_DANGEROUS_RE.some(re => re.test(cmd))) return TIERS.SHELL_DANGEROUS;
 
+  if (hasUnsafeOutputRedirection(cmd)) return TIERS.SHELL_MEDIUM;
+
   // For a chained command, classify each segment and take the riskiest —
   // never let a safe-looking prefix mask `&& npm install` or worse.
   if (/&&|\|\||;|\|(?!\|)/.test(cmd)) {
@@ -161,6 +178,31 @@ export function classifyShell(command) {
   return TIERS.SHELL_MEDIUM;
 }
 
+function hasUnsafeOutputRedirection(cmd) {
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i];
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\' && !inSingle) { escaped = true; continue; }
+    if (ch === "'" && !inDouble) { inSingle = !inSingle; continue; }
+    if (ch === '"' && !inSingle) { inDouble = !inDouble; continue; }
+    if (inSingle || inDouble || ch !== '>') continue;
+
+    const prev = cmd[i - 1] || '';
+    const next = cmd[i + 1] || '';
+    if (next === '&') continue;
+    let cursor = next === '>' ? i + 2 : i + 1;
+    while (/\s/.test(cmd[cursor] || '')) cursor++;
+    const target = cmd.slice(cursor).match(/^[^\s;&|]+/)?.[0] || '';
+    if (target === '/dev/null') continue;
+    if (prev === '2' && target === '/dev/null') continue;
+    return true;
+  }
+  return false;
+}
+
 function splitShellSegments(cmd) {
   // Split on top-level &&, ||, ;, | — naive but enough for the classifier.
   return cmd.split(/&&|\|\||;|\|/).map(s => s.trim()).filter(Boolean);
@@ -168,6 +210,7 @@ function splitShellSegments(cmd) {
 
 const TIER_ORDER = [
   TIERS.READ,
+  TIERS.SENSITIVE_READ,
   TIERS.SHELL_SAFE,
   TIERS.LOCAL_EDIT,
   TIERS.NETWORK,
@@ -191,7 +234,9 @@ function riskier(a, b) {
 export function classify(tool, args = {}) {
   if (!tool) return TIERS.SHELL_MEDIUM;
 
-  if (READ_TOOLS.has(tool))        return TIERS.READ;
+  if (READ_TOOLS.has(tool)) {
+    return isSensitiveRead(args) ? TIERS.SENSITIVE_READ : TIERS.READ;
+  }
   if (LOCAL_EDIT_TOOLS.has(tool))  return TIERS.LOCAL_EDIT;
   if (DESTRUCTIVE_TOOLS.has(tool)) return TIERS.DESTRUCTIVE;
   if (NETWORK_TOOLS.has(tool))     return TIERS.NETWORK;
@@ -220,6 +265,7 @@ export function classify(tool, args = {}) {
 export function label(tier) {
   switch (tier) {
     case TIERS.READ:            return 'READ';
+    case TIERS.SENSITIVE_READ:  return 'SENSITIVE-READ';
     case TIERS.LOCAL_EDIT:      return 'LOCAL-EDIT';
     case TIERS.SHELL_SAFE:      return 'SHELL-SAFE';
     case TIERS.SHELL_MEDIUM:    return 'SHELL-MEDIUM';
@@ -243,3 +289,43 @@ export function requiresExplicitApproval(tier) {
 export function requiresCheckpoint(tier) {
   return behavior(tier) === 'auto-with-undo';
 }
+
+export function isSensitiveRead(args = {}) {
+  return extractReadPaths(args).some(isSensitiveReadPath);
+}
+
+export function isSensitiveReadPath(filePath = '') {
+  const normalized = String(filePath || '')
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .replace(/^\.\//, '')
+    .trim();
+  if (!normalized) return false;
+
+  const parts = normalized.split('/').filter(Boolean);
+  const base = parts[parts.length - 1] || normalized;
+  if (base === '.env') return true;
+  if (/\.pem$/i.test(base)) return true;
+  return parts.includes('secrets');
+}
+
+function extractReadPaths(args = {}) {
+  const paths = [];
+  for (const key of READ_PATH_KEYS) {
+    if (typeof args[key] === 'string') paths.push(args[key]);
+  }
+  for (const key of READ_PATH_ARRAY_KEYS) {
+    const value = args[key];
+    if (!Array.isArray(value)) continue;
+    for (const item of value) {
+      if (typeof item === 'string') {
+        paths.push(item);
+      } else if (item && typeof item === 'object') {
+        for (const nestedKey of READ_PATH_KEYS) {
+          if (typeof item[nestedKey] === 'string') paths.push(item[nestedKey]);
+        }
+      }
+    }
+  }
+  return paths;
+}

package/src/core/safety.mjs

@@ -67,6 +67,9 @@ const HIGH_RISK_COMMANDS = [
   /\brm\s/,                    // ALL rm commands require explicit approval
   /\bunlink\s/,                // unlink
   /\brmdir\s/,                 // rmdir
+  /\bkill\s/,                  // process termination requires explicit approval
+  /\bpkill\s/,                 // process termination by pattern requires explicit approval
+  /\bxargs\s+kill\b/,          // process termination via piped pid list
   /git\s+push\s+--force/,
   /git\s+reset\s+--hard/,
   /git\s+clean\s+-[fd]/,

package/src/core/session-manager.mjs

@@ -210,16 +210,54 @@ export class SessionManager {
      * @returns {{ role: string, content: string }[]}
      */
     loadMessages(sessionId) {
+        return this.loadConversation(sessionId).messages;
+    }
+
+    /**
+     * Load the header and all messages from a session conversation file.
+     * @param {string} sessionId
+     * @returns {{ header: object|null, messages: { role: string, content: string }[] }}
+     */
+    loadConversation(sessionId) {
         const filePath = this._conversationPath(sessionId);
-        if (!fs.existsSync(filePath)) return [];
+        if (!fs.existsSync(filePath)) return { header: null, messages: [] };
 
         const lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
-        return lines
+        const entries = lines
             .map(line => {
                 try { return JSON.parse(line); } catch { return null; }
             })
-            .filter(entry => entry && entry.role) // skip header (type=header, no role)
+            .filter(Boolean);
+        const header = entries.find(entry => entry.type === 'header') || null;
+        const messages = entries
+            .filter(entry => entry.role) // skip header (type=header, no role)
             .map(entry => ({ role: entry.role, content: entry.content }));
+        return { header, messages };
+    }
+
+    /**
+     * Activate an existing conversation as the current session so additional
+     * turns append to the same JSONL file.
+     * @param {string} sessionId
+     * @param {object|null} header
+     * @param {{ role: string, content: string }[]} messages
+     */
+    activateSession(sessionId, header = null, messages = []) {
+        this._ensureDirs();
+        this.currentState = {
+            instruction: header?.instruction || messages.find(m => m.role === 'user')?.content || '',
+            started_at: header?.started_at || new Date().toISOString(),
+            status: 'running',
+            task_id: null,
+            job_id: null,
+            session_id: sessionId,
+            tool_count: 0,
+            turn_count: messages.filter(m => m.role === 'user').length,
+            events: [],
+            resumed_at: new Date().toISOString(),
+        };
+        this._writeState();
+        return this.currentState;
     }
 
     /**
@@ -249,29 +287,32 @@ export class SessionManager {
             instruction: header?.instruction || '',
             startedAt: header?.started_at || '',
             project: header?.project_name || '',
+            projectPath: header?.project || '',
         };
     }
 
     /**
      * List sessions that have conversation history (resumable).
      * Reads metadata from JSONL header line — no cross-referencing needed.
-     * @param {number} [limit=10]
-     * @returns {Array<{ sessionId, instruction, startedAt, project, messageCount }>}
+     * @param {number} [limit=Infinity]
+     * @returns {Array<{ sessionId, instruction, startedAt, updatedAt, project, messageCount }>}
      */
-    listResumable(limit = 10) {
+    listResumable(limit = Infinity) {
         if (!fs.existsSync(this.conversationsDir)) return [];
 
-        // Sort by modification time (most recent first)
+        // Sort by latest activity (conversation file mtime) so resumed sessions
+        // move back to the top. The UI displays this same timestamp.
         const files = fs.readdirSync(this.conversationsDir)
             .filter(f => f.endsWith('.jsonl'))
             .map(f => ({
                 name: f,
                 mtime: fs.statSync(path.join(this.conversationsDir, f)).mtimeMs,
             }))
-            .sort((a, b) => b.mtime - a.mtime)
-            .slice(0, limit);
+            .sort((a, b) => b.mtime - a.mtime);
+
+        const limited = Number.isFinite(limit) ? files.slice(0, limit) : files;
 
-        return files.map(({ name }) => {
+        return limited.map(({ name, mtime }) => {
             const sessionId = name.replace('.jsonl', '');
             const convPath = path.join(this.conversationsDir, name);
             const lines = fs.readFileSync(convPath, 'utf-8').split('\n').filter(Boolean);
@@ -284,7 +325,9 @@ export class SessionManager {
                 sessionId,
                 instruction: header?.instruction || '(no instruction)',
                 startedAt: header?.started_at || '',
+                updatedAt: new Date(mtime).toISOString(),
                 project: header?.project_name || '',
+                projectPath: header?.project || '',
                 messageCount,
             };
         });

package/src/core/stream-client.mjs

@@ -11,6 +11,7 @@
 
 import { sendCallback, sendSkippedCallback, sendApprovalDecision } from './callback-client.mjs';
 import { ApprovalManager } from './approval.mjs';
+import { rateLimitErrorMessage } from './rate-limit-display.mjs';
 
 export const EVENT_TYPES = Object.freeze({
     // Phase 1 — handled
@@ -57,18 +58,26 @@ export class TarangStreamClient {
      * @param {Object} opts.toolExecutor - { execute(name, args) }
      * @param {boolean} [opts.verbose=false]
      */
-    constructor({ baseUrl, token, toolExecutor, verbose = false, approvalManager = null }) {
+    constructor({ baseUrl, token, toolExecutor, verbose = false, approvalManager = null, product = null }) {
         this.baseUrl = (baseUrl || '').replace(/\/$/, '');
         this.token = token;
         this.toolExecutor = toolExecutor;
         this.verbose = verbose;
         this.approval = approvalManager || new ApprovalManager();
+        this.product = product || process.env.TARANG_PRODUCT || process.env.KEPLER_PRODUCT || 'kepler';
         this.currentTaskId = null;
         this.sessionId = null;  // Set by backend on first turn, reused on subsequent turns
         this._cancelled = false;
         this._paused = false;
     }
 
+    _headers(extra = {}) {
+        const headers = { ...extra };
+        if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
+        if (this.product) headers['X-Product'] = this.product;
+        return headers;
+    }
+
     /**
      * Execute an instruction via SSE stream.
      * Yields parsed events. Client-side tool requests are shown, executed
@@ -87,11 +96,10 @@ export class TarangStreamClient {
         if (messages && messages.length > 0) body.messages = messages;
         if (this.sessionId) body.session_id = this.sessionId;
 
-        const headers = {
+        const headers = this._headers({
             'Accept': 'text/event-stream',
             'Content-Type': 'application/json',
-        };
-        if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
+        });
 
         // Abort controller so cancel() can break out of a stalled reader
         // instead of waiting for the next SSE event to notice _cancelled.
@@ -118,6 +126,27 @@ export class TarangStreamClient {
             yield { type: EVENT_TYPES.ERROR, data: { message: 'Authentication failed. Run `kepler login` to re-authenticate.', fatal: true } };
             return;
         }
+        if (response.status === 429) {
+            const text = await response.text().catch(() => '');
+            let payload = null;
+            try {
+                payload = text ? JSON.parse(text) : null;
+            } catch {
+                payload = { detail: { message: text } };
+            }
+            const detail = payload?.detail && typeof payload.detail === 'object' ? payload.detail : payload;
+            yield {
+                type: EVENT_TYPES.ERROR,
+                data: {
+                    message: rateLimitErrorMessage(payload),
+                    code: detail?.code || 'rate_limited',
+                    retry_after: detail?.retry_after ?? detail?.rate_limit?.retry_after,
+                    rate_limit: detail?.rate_limit || null,
+                    fatal: true,
+                },
+            };
+            return;
+        }
         if (!response.ok) {
             const text = await response.text().catch(() => 'Unknown error');
             yield { type: EVENT_TYPES.ERROR, data: { message: `Backend error ${response.status}: ${text}`, fatal: true } };
@@ -307,7 +336,7 @@ export class TarangStreamClient {
         }
 
         // Use the same ApprovalManager for consistent UX
-        const { approved, reason: denyReason } = await this.approval.check(
+        const { approved, reason: denyReason, scope: approvedScope } = await this.approval.check(
             tool,
             args || {},
             true,
@@ -323,6 +352,8 @@ export class TarangStreamClient {
                 scope = 'all';
             } else if (this.approval.approvedToolTypes.has(tool)) {
                 scope = 'type';
+            } else if (approvedScope) {
+                scope = String(approvedScope).toLowerCase();
             } else {
                 scope = 'once';
             }
@@ -357,7 +388,7 @@ export class TarangStreamClient {
             try {
                 await fetch(`${this.baseUrl}/api/cancel/${this.currentTaskId}`, {
                     method: 'POST',
-                    headers: { 'Authorization': `Bearer ${this.token}` },
+                    headers: this._headers(),
                 });
             } catch { /* best effort */ }
         }
@@ -373,7 +404,7 @@ export class TarangStreamClient {
         if (this.currentTaskId) {
             await fetch(`${this.baseUrl}/api/pause/${this.currentTaskId}`, {
                 method: 'POST',
-                headers: { 'Authorization': `Bearer ${this.token}` },
+                headers: this._headers(),
             });
         }
     }
@@ -384,12 +415,40 @@ export class TarangStreamClient {
             const body = instruction ? JSON.stringify({ instruction }) : undefined;
             await fetch(`${this.baseUrl}/api/resume/${this.currentTaskId}`, {
                 method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this.token}`,
+                headers: this._headers({
                     'Content-Type': 'application/json',
-                },
+                }),
                 body,
             });
         }
     }
+
+    /**
+     * Summarize a prior transcript for resume continuity.
+     *
+     * @param {Array<{role:string,content:string}>} messages
+     * @param {Object} [opts]
+     * @returns {Promise<{summary:string,source:string,model:string}>}
+     */
+    async summarizeSession(messages, opts = {}) {
+        const response = await fetch(`${this.baseUrl}/api/summarize/session`, {
+            method: 'POST',
+            headers: this._headers({
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            }),
+            body: JSON.stringify({
+                messages,
+                session_id: opts.sessionId || null,
+                project_path: opts.projectPath || null,
+                max_tokens: opts.maxTokens || 800,
+            }),
+            signal: AbortSignal.timeout(opts.timeoutMs || 15000),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`summary request failed (${response.status})${text ? `: ${text.slice(0, 200)}` : ''}`);
+        }
+        return await response.json();
+    }
 }

package/src/core/system-prompt.mjs

@@ -1,5 +1,5 @@
 /**
- * System Prompt Builder — loads and merges CLAUDE.md files.
+ * System Prompt Builder — loads and merges CLAUDE.md and KEPLER.md files.
  *
  * Features:
  * - Loads CLAUDE.md from: ~/.claude/CLAUDE.md, project root, parent dirs
@@ -10,6 +10,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { loadKeplerMemory } from '../config/memory-loader.mjs';
 
 /**
  * Load all CLAUDE.md files and merge them in order.
@@ -88,6 +89,10 @@ export function buildSystemPrompt({ cwd, tools, override, addDirs } = {}) {
         parts.push(f.content);
     }
 
+    for (const f of loadKeplerMemory({ cwd })) {
+        parts.push(f.content);
+    }
+
     // The static prefix is the base prompt + CLAUDE.md content (cacheable)
     const staticPrefix = parts.join('\n\n');
 

package/src/core/tasks.mjs

@@ -0,0 +1,196 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const TASK_FILES = Object.freeze({
+  active: 'active.md',
+  backlog: 'backlog.md',
+  blocked: 'blocked.md',
+  done: 'done.md',
+});
+
+const DEFAULT_CONTENT = Object.freeze({
+  'README.md': '# Kepler Tasks\n\nChecklist files are read every turn.\n',
+  'active.md': '# Active\n\n',
+  'backlog.md': '# Backlog\n\n',
+  'blocked.md': '# Blocked\n\n',
+  'done.md': '# Done\n\n',
+});
+
+export function ensureTaskFiles({ cwd = process.cwd() } = {}) {
+  const dir = path.join(cwd, '.kepler', 'tasks');
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const [name, content] of Object.entries(DEFAULT_CONTENT)) {
+    const filePath = path.join(dir, name);
+    if (fs.existsSync(filePath)) continue;
+    fs.writeFileSync(filePath, content);
+    written.push(filePath);
+  }
+  return { dir, written };
+}
+
+export function loadTaskBoard({ cwd = process.cwd(), create = false } = {}) {
+  const dir = path.join(cwd, '.kepler', 'tasks');
+  if (create) ensureTaskFiles({ cwd });
+  const lists = {};
+  for (const [list, fileName] of Object.entries(TASK_FILES)) {
+    const filePath = path.join(dir, fileName);
+    const content = readText(filePath);
+    lists[list] = {
+      list,
+      fileName,
+      path: filePath,
+      exists: fs.existsSync(filePath),
+      content,
+      tasks: parseTaskMarkdown(content, list),
+    };
+  }
+
+  const planPath = path.join(cwd, '.kepler', 'plan.md');
+  const goalPath = path.join(cwd, '.kepler', 'goal.md');
+  return {
+    dir,
+    lists,
+    plan: { path: planPath, exists: fs.existsSync(planPath), content: readText(planPath) },
+    goal: { path: goalPath, exists: fs.existsSync(goalPath), content: readText(goalPath) },
+  };
+}
+
+export function appendTask({ cwd = process.cwd(), list = 'backlog', text }) {
+  const normalized = normalizeList(list);
+  const taskText = String(text || '').trim();
+  if (!taskText) throw new Error('Task text is required');
+  const { dir } = ensureTaskFiles({ cwd });
+  const filePath = path.join(dir, TASK_FILES[normalized]);
+  const prefix = normalized === 'done' ? '- [x]' : '- [ ]';
+  fs.appendFileSync(filePath, `${prefix} ${taskText}\n`);
+  return { list: normalized, path: filePath, text: taskText };
+}
+
+export function updateTask({ cwd = process.cwd(), list = 'active', index, text, checked } = {}) {
+  const normalized = normalizeList(list);
+  const taskIndex = normalizeTaskIndex(index);
+  ensureTaskFiles({ cwd });
+  const filePath = taskFilePath(cwd, normalized);
+  const content = readText(filePath);
+  const tasks = parseTaskMarkdown(content, normalized);
+  const task = tasks[taskIndex - 1];
+  if (!task) throw new Error(`No task ${taskIndex} in ${normalized}`);
+
+  const lines = content.split(/\r?\n/);
+  const nextText = String(text ?? task.text).trim();
+  if (!nextText) throw new Error('Task text is required');
+  const nextChecked = checked === undefined ? task.checked : Boolean(checked);
+  lines[task.line - 1] = taskLine(nextText, normalized, nextChecked);
+  fs.writeFileSync(filePath, lines.join('\n'));
+  return { list: normalized, path: filePath, index: taskIndex, previous: task, text: nextText, checked: nextChecked };
+}
+
+export function removeTask({ cwd = process.cwd(), list = 'active', index } = {}) {
+  const normalized = normalizeList(list);
+  const taskIndex = normalizeTaskIndex(index);
+  ensureTaskFiles({ cwd });
+  const filePath = taskFilePath(cwd, normalized);
+  const content = readText(filePath);
+  const tasks = parseTaskMarkdown(content, normalized);
+  const task = tasks[taskIndex - 1];
+  if (!task) throw new Error(`No task ${taskIndex} in ${normalized}`);
+
+  const lines = content.split(/\r?\n/);
+  lines.splice(task.line - 1, 1);
+  fs.writeFileSync(filePath, lines.join('\n'));
+  return { list: normalized, path: filePath, index: taskIndex, task };
+}
+
+export function moveTask({ cwd = process.cwd(), from = 'active', index, to = 'done', text } = {}) {
+  const source = normalizeList(from);
+  const target = normalizeList(to);
+  const removed = removeTask({ cwd, list: source, index });
+  const taskText = String(text ?? removed.task.text).trim();
+  const appended = appendTask({ cwd, list: target, text: taskText });
+  return {
+    from: source,
+    to: target,
+    index: removed.index,
+    text: taskText,
+    sourcePath: removed.path,
+    targetPath: appended.path,
+  };
+}
+
+export function taskCounts(board) {
+  const lists = board?.lists || {};
+  return Object.fromEntries(
+    Object.entries(TASK_FILES).map(([list]) => [list, lists[list]?.tasks?.length || 0]),
+  );
+}
+
+export function normalizeList(value) {
+  const key = String(value || '').toLowerCase();
+  if (key === 'todo' || key === 'pending') return 'backlog';
+  if (key === 'current' || key === 'doing') return 'active';
+  if (key === 'complete' || key === 'completed') return 'done';
+  if (key in TASK_FILES) return key;
+  throw new Error(`Unknown task list: ${value}`);
+}
+
+function normalizeTaskIndex(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error('Task index must be a positive number');
+  return n;
+}
+
+function taskFilePath(cwd, list) {
+  return path.join(cwd, '.kepler', 'tasks', TASK_FILES[list]);
+}
+
+function taskLine(text, list, checked = false) {
+  const mark = checked || list === 'done' ? 'x' : ' ';
+  return `- [${mark}] ${text}`;
+}
+
+function readText(filePath) {
+  try {
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+  } catch {
+    return '';
+  }
+}
+
+export function parseTaskMarkdown(content, list = 'backlog') {
+  const tasks = [];
+  let section = '';
+  const lines = String(content || '').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const heading = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (heading) {
+      section = heading[1].trim();
+      continue;
+    }
+
+    const checkbox = line.match(/^\s*[-*]\s+\[([ xX!-])\]\s+(.+?)\s*$/);
+    if (checkbox) {
+      tasks.push({
+        list,
+        line: i + 1,
+        section,
+        checked: checkbox[1].toLowerCase() === 'x',
+        text: checkbox[2].trim(),
+      });
+      continue;
+    }
+
+    const bullet = line.match(/^\s*[-*]\s+(.+?)\s*$/);
+    if (bullet && !bullet[1].startsWith('`')) {
+      tasks.push({
+        list,
+        line: i + 1,
+        section,
+        checked: list === 'done',
+        text: bullet[1].trim(),
+      });
+    }
+  }
+  return tasks;
+}