@thesammykins/tether 1.3.0 → 1.4.0

package/bin/tether.ts

@@ -1010,7 +1010,12 @@ async function configCommand() {
                     console.error('Password cannot be empty');
                     process.exit(1);
                 }
-                writeSecret(key, value, pw);
+                try {
+                    writeSecret(key, value, pw);
+                } catch (err) {
+                    console.error(err instanceof Error ? err.message : 'Failed to save secret');
+                    process.exit(1);
+                }
                 console.log(`✔ Secret "${key}" saved (encrypted)`);
             } else {
                 if (value === undefined) {

package/docs/architecture.md

@@ -37,6 +37,20 @@ The bot handles Discord events, the queue provides durability and backpressure,
 6. Adapter runs the CLI (`claude`/`opencode`/`codex`) with the prompt
 7. Worker posts the agent's response back to the Discord thread
 
+### Forum Channels
+
+When `FORUM_SESSIONS=true` and `FORUM_CHANNEL_ID` is set:
+
+1. User `@mentions` the bot in any channel
+2. Bot runs the middleware pipeline (allowlist → rate limiter → pause check)
+3. Bot creates a **forum post** in the configured forum channel (instead of a thread)
+4. Bot replies in the original channel with a link to the forum post
+5. Bot adds a job to the BullMQ queue
+6. Worker posts the response in the forum post
+7. Follow-up messages in the forum post continue the same session
+
+Forum threads use the same `thread_id → session_id` DB mapping as regular threads — no schema differences.
+
 ### Direct Messages
 
 1. User sends a message to the bot in DMs (no `@mention` needed)

package/docs/configuration.md

@@ -88,13 +88,67 @@ tether config list
 | `REDIS_HOST` | `localhost` | Redis host |
 | `REDIS_PORT` | `6379` | Redis port |
 
-### Security
+### Security & Access Control
+
+Tether supports restricting who can interact with the bot using allowlists. If none are configured, the bot responds to all users.
+
+#### User Allowlist
+
+Restrict the bot to only respond to specific Discord users:
+
+```bash
+# Set allowed users (comma-separated Discord user IDs)
+tether config set ALLOWED_USERS 123456789012345678,987654321098765432
+```
+
+**How to find your Discord user ID:**
+
+1. Enable **Developer Mode** in Discord: Settings → App Settings → Advanced → Developer Mode
+2. Right-click on your username (or any user) → **Copy ID**
+
+When `ALLOWED_USERS` is set, only users in the list can interact with the bot. This works in both guild channels and DMs.
+
+#### Role and Channel Allowlists
+
+For guild (server) deployments, you can also restrict by role or channel:
+
+```bash
+# Only allow users with specific roles (comma-separated role IDs)
+tether config set ALLOWED_ROLES 111111111111111111,222222222222222222
+
+# Only allow bot usage in specific channels (comma-separated channel IDs)
+tether config set ALLOWED_CHANNELS 333333333333333333,444444444444444444
+```
+
+**How these work together:**
+- If `ALLOWED_CHANNELS` is set, messages must be in an allowed channel (or its threads)
+- If `ALLOWED_USERS` or `ALLOWED_ROLES` is set, the user must match at least one:
+  - Be in the `ALLOWED_USERS` list, OR
+  - Have a role in the `ALLOWED_ROLES` list
+- Role and channel allowlists only apply in guilds (not DMs)
+- If no allowlists are configured, the bot responds to everyone
+
+**Examples:**
+
+```bash
+# Only respond to yourself
+tether config set ALLOWED_USERS 123456789012345678
+
+# Only respond in a specific channel
+tether config set ALLOWED_CHANNELS 987654321098765432
+
+# Only respond to admins (role ID)
+tether config set ALLOWED_ROLES 555555555555555555
+
+# Combine: only respond to specific users in specific channels
+tether config set ALLOWED_USERS 123456789012345678
+tether config set ALLOWED_CHANNELS 987654321098765432
+```
+
+#### Directory Allowlist
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `ALLOWED_USERS` | (empty = all) | Comma-separated Discord user IDs |
-| `ALLOWED_ROLES` | (empty = all) | Comma-separated Discord role IDs (guild only) |
-| `ALLOWED_CHANNELS` | (empty = all) | Comma-separated Discord channel IDs (guild only) |
 | `CORD_ALLOWED_DIRS` | (empty = any) | Comma-separated allowed working directories |
 
 ### Limits
@@ -114,6 +168,17 @@ tether config list
 | `FORUM_SESSIONS` | `false` | Use forum channel posts instead of text channel threads for sessions |
 | `FORUM_CHANNEL_ID` | (empty) | Discord forum channel ID for session posts (required when `FORUM_SESSIONS=true`) |
 
+#### Forum Sessions
+
+By default, Tether creates threads in the channel where the bot is mentioned. When forum sessions are enabled, it creates forum posts in a dedicated forum channel instead — useful for keeping conversations organized and searchable.
+
+```bash
+tether config set FORUM_SESSIONS true
+tether config set FORUM_CHANNEL_ID 123456789012345678
+```
+
+Both keys are required. See [Discord Setup — Forum Channels](discord-setup.md#6-use-forum-channels-optional) for the full setup guide.
+
 ### Database
 
 | Key | Default | Description |
@@ -154,7 +219,4 @@ Paths outside the allowlist are rejected. If unset, any existing directory is al
 
 ## Finding Discord IDs
 
-To get user, role, or channel IDs:
-
-1. Enable **Developer Mode** in Discord: Settings → App Settings → Advanced → Developer Mode
-2. Right-click a user, role, or channel → **Copy ID**
+See the [Security & Access Control](#security--access-control) section above for instructions on finding user, role, and channel IDs.

package/docs/discord-setup.md

@@ -64,7 +64,34 @@ The bot needs these permissions in your server:
 4. Copy the generated URL and open it in your browser
 5. Select the server you want to add the bot to and click **Authorize**
 
-## 6. Enable DMs (Optional)
+## 6. Use Forum Channels (Optional)
+
+By default, Tether creates threads in the channel where the bot is mentioned. If you prefer organized, searchable forum posts instead:
+
+1. Create a **Forum Channel** in your Discord server (Server Settings → Channels → Create Channel → Forum)
+2. Configure Tether to use it:
+   ```bash
+   tether config set FORUM_SESSIONS true
+   tether config set FORUM_CHANNEL_ID 123456789012345678
+   ```
+3. Restart Tether (`tether stop && tether start`)
+
+### Forum Behavior
+
+- When someone `@mentions` the bot in any channel, a new **forum post** is created in your forum channel instead of a thread
+- The bot replies in the original channel with a link to the forum post
+- Follow-up messages in the forum post continue the same session — no `@mention` needed
+- Session reuse, pause/resume, BRB, and ✅ completion all work the same as regular threads
+- The forum post title is auto-generated from the first prompt
+
+### Finding the Forum Channel ID
+
+1. Enable **Developer Mode** (see [Finding Discord IDs](#finding-discord-ids) below)
+2. Right-click the forum channel → **Copy ID**
+
+> **Note:** The bot needs **Send Messages**, **Create Posts**, and **Send Messages in Threads** permissions in the forum channel.
+
+## 7. Enable DMs (Optional)
 
 If you want users to DM the bot directly:
 
@@ -82,7 +109,7 @@ If you want users to DM the bot directly:
 - Send `!reset` in DMs to start a fresh session
 - Only `ALLOWED_USERS` is checked for DMs (roles and channels don't apply)
 
-## 7. Start and Test
+## 8. Start and Test
 
 ```bash
 # Start Redis (if not already running)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thesammykins/tether",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Discord bot that bridges messages to AI agent sessions (Claude, OpenCode, Codex)",
   "license": "MIT",
   "author": "thesammykins",

package/src/adapters/claude.ts

@@ -9,12 +9,114 @@ import type { AgentAdapter, SpawnOptions, SpawnResult } from './types.js';
  * - `--print`: Non-interactive mode, returns output
  * - `--session-id UUID`: Set session ID for new sessions
  * - `--resume UUID`: Resume an existing session (for follow-ups)
+ * - `--continue` / `-c`: Resume latest session in directory (fallback)
  * - `--append-system-prompt`: Inject context that survives compaction
  * - `-p "prompt"`: The actual prompt to send
  * - `--output-format json`: Structured output (if supported)
+ * 
+ * Known Issues:
+ * - GitHub Issue #5012: `--resume` was broken in v1.0.67
+ * - Sessions are directory-scoped; must resume from same cwd
+ * - `--continue` is preferred fallback when `--resume` fails
  */
 
 const TIMEZONE = process.env.TZ || 'UTC';
+const KNOWN_BUGGY_VERSIONS = ['1.0.67'];
+
+// Cache resolved binary path
+let cachedBinaryPath: string | null = null;
+
+/**
+ * Resolve the Claude CLI binary path.
+ * Tries `which claude` (macOS/Linux) or `where.exe claude` (Windows),
+ * then falls back to checking `npx @anthropic-ai/claude-code` availability.
+ */
+async function getClaudeBinaryPath(): Promise<string> {
+  if (cachedBinaryPath) {
+    return cachedBinaryPath;
+  }
+
+  const isWindows = process.platform === 'win32';
+  const whichCommand = isWindows ? 'where.exe' : 'which';
+
+  try {
+    const proc = Bun.spawn([whichCommand, 'claude'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode === 0 && stdout.trim()) {
+      cachedBinaryPath = 'claude';
+      console.log(`[claude] Binary found at: ${stdout.trim()}`);
+      return cachedBinaryPath;
+    }
+  } catch (err) {
+    // Fall through to npx check
+  }
+
+  // Try npx fallback
+  try {
+    const proc = Bun.spawn(['npx', '--version'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const exitCode = await proc.exited;
+
+    if (exitCode === 0) {
+      cachedBinaryPath = 'npx';
+      console.log('[claude] Binary not in PATH, will use: npx @anthropic-ai/claude-code');
+      return cachedBinaryPath;
+    }
+  } catch (err) {
+    // Fall through to error
+  }
+
+  throw new Error(
+    'Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code'
+  );
+}
+
+/**
+ * Get the Claude CLI version.
+ * Runs `claude --version` and parses the output.
+ */
+async function getClaudeVersion(binaryPath: string): Promise<string> {
+  const args = binaryPath === 'npx'
+    ? ['npx', '@anthropic-ai/claude-code', '--version']
+    : [binaryPath, '--version'];
+
+  try {
+    const proc = Bun.spawn(args, {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode === 0) {
+      const version = stdout.trim();
+      console.log(`[claude] CLI version: ${version}`);
+
+      // Warn if known buggy version
+      if (KNOWN_BUGGY_VERSIONS.some((v) => version.includes(v))) {
+        console.warn(
+          `[claude] WARNING: Version ${version} has known issues with --resume (GitHub #5012)`
+        );
+      }
+
+      return version;
+    }
+  } catch (err) {
+    console.warn('[claude] Could not determine CLI version:', err);
+  }
+
+  return 'unknown';
+}
 
 function getDatetimeContext(): string {
   const now = new Date();
@@ -38,8 +140,35 @@ export class ClaudeAdapter implements AgentAdapter {
 
     const cwd = workingDir || process.env.CLAUDE_WORKING_DIR || process.cwd();
 
+    // Resolve binary path and get version
+    const binaryPath = await getClaudeBinaryPath();
+    await getClaudeVersion(binaryPath);
+
     // Build CLI arguments
-    const args = ['claude'];
+    const args = this.buildArgs(binaryPath, options);
+
+    console.log('[claude] Spawning with args:', args);
+    console.log('[claude] Working directory:', cwd);
+
+    // Spawn the process
+    const result = await this.spawnProcess(args, cwd, sessionId, resume);
+
+    return result;
+  }
+
+  /**
+   * Build CLI arguments based on options.
+   */
+  private buildArgs(binaryPath: string, options: SpawnOptions): string[] {
+    const { prompt, sessionId, resume, systemPrompt } = options;
+
+    const args: string[] = [];
+
+    if (binaryPath === 'npx') {
+      args.push('npx', '@anthropic-ai/claude-code');
+    } else {
+      args.push(binaryPath);
+    }
 
     // Non-interactive mode
     args.push('--print');
@@ -67,8 +196,19 @@ export class ClaudeAdapter implements AgentAdapter {
     // The actual prompt
     args.push('-p', prompt);
 
-    // Spawn the process
-    const proc = Bun.spawn(args, {
+    return args;
+  }
+
+  /**
+   * Spawn the Claude process and handle fallback for resume failures.
+   */
+  private async spawnProcess(
+    args: string[],
+    cwd: string,
+    sessionId: string,
+    resume: boolean
+  ): Promise<SpawnResult> {
+    let proc = Bun.spawn(args, {
       cwd,
       env: {
         ...process.env,
@@ -79,11 +219,61 @@ export class ClaudeAdapter implements AgentAdapter {
     });
 
     // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
+    let stdout = await new Response(proc.stdout).text();
+    let stderr = await new Response(proc.stderr).text();
 
     // Wait for process to exit
-    const exitCode = await proc.exited;
+    let exitCode = await proc.exited;
+
+    console.log('[claude] Exit code:', exitCode);
+    if (stderr) {
+      console.log('[claude] Stderr:', stderr);
+    }
+
+    // Handle --resume fallback
+    if (
+      resume &&
+      exitCode !== 0 &&
+      (stderr.includes('No conversation found') || stderr.includes('Session not found'))
+    ) {
+      console.log(
+        `[claude] --resume failed for ${sessionId}, falling back to --continue`
+      );
+
+      // Rebuild args with --continue instead of --resume
+      const continueArgs = args.map((arg, i) => {
+        if (arg === '--resume') {
+          return '--continue';
+        }
+        // Skip the session ID that follows --resume
+        if (i > 0 && args[i - 1] === '--resume') {
+          return null;
+        }
+        return arg;
+      }).filter((arg): arg is string => arg !== null);
+
+      console.log('[claude] Retrying with args:', continueArgs);
+
+      // Retry with --continue
+      proc = Bun.spawn(continueArgs, {
+        cwd,
+        env: {
+          ...process.env,
+          TZ: TIMEZONE,
+        },
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+
+      stdout = await new Response(proc.stdout).text();
+      stderr = await new Response(proc.stderr).text();
+      exitCode = await proc.exited;
+
+      console.log('[claude] Fallback exit code:', exitCode);
+      if (stderr) {
+        console.log('[claude] Fallback stderr:', stderr);
+      }
+    }
 
     if (exitCode !== 0) {
       throw new Error(`Claude CLI failed (exit ${exitCode}): ${stderr || 'Unknown error'}`);

package/src/bot.ts

@@ -36,6 +36,7 @@ import { generateThreadName } from './features/thread-naming.js';
 import { checkSessionLimits } from './features/session-limits.js';
 import { handlePauseResume } from './features/pause-resume.js';
 import { isBrbMessage, isBackMessage, setBrb, setBack } from './features/brb.js';
+import { listSessions, formatAge } from './features/sessions.js';
 import { questionResponses, pendingTypedAnswers } from './api.js';
 
 // DM support - opt-in via env var (disabled by default for security)
@@ -146,24 +147,43 @@ client.once(Events.ClientReady, async (c) => {
     const existingCommands = await c.application?.commands.fetch();
     const cordCommand = existingCommands?.find(cmd => cmd.name === 'cord');
 
-    if (!cordCommand) {
-        const command = new SlashCommandBuilder()
-            .setName('cord')
-            .setDescription('Configure Cord bot')
-            .addSubcommand(sub =>
-                sub.setName('config')
-                   .setDescription('Configure channel settings')
-                   .addStringOption(opt =>
-                       opt.setName('dir')
-                          .setDescription('Working directory for Claude in this channel')
-                          .setRequired(true)
-                   )
-            );
+    // Always re-register to pick up new subcommands
+    const command = new SlashCommandBuilder()
+        .setName('cord')
+        .setDescription('Configure Cord bot')
+        .addSubcommand(sub =>
+            sub.setName('config')
+               .setDescription('Configure channel settings')
+               .addStringOption(opt =>
+                   opt.setName('dir')
+                      .setDescription('Working directory for Claude in this channel')
+                      .setRequired(true)
+               )
+        )
+        .addSubcommand(sub =>
+            sub.setName('sessions')
+               .setDescription('List resumable Claude Code sessions')
+               .addStringOption(opt =>
+                   opt.setName('dir')
+                      .setDescription('Project directory to list sessions for (defaults to channel config)')
+                      .setRequired(false)
+               )
+               .addIntegerOption(opt =>
+                   opt.setName('limit')
+                      .setDescription('Max sessions to show (default 5)')
+                      .setRequired(false)
+                      .setMinValue(1)
+                      .setMaxValue(25)
+               )
+        );
 
+    if (!cordCommand) {
         await c.application?.commands.create(command);
         log('Slash commands registered');
     } else {
-        log('Slash commands already registered');
+        // Update existing command to include new subcommands
+        await cordCommand.edit(command);
+        log('Slash commands updated');
     }
 
     // Start HTTP API server
@@ -204,6 +224,48 @@ client.on(Events.InteractionCreate, async (interaction: Interaction) => {
             });
             log(`Channel ${interaction.channelId} configured with working dir: ${dir}`);
         }
+
+        if (subcommand === 'sessions') {
+            // Resolve project directory: explicit option > channel config > env > cwd
+            let projectDir = interaction.options.getString('dir');
+            if (projectDir) {
+                if (projectDir.startsWith('~')) {
+                    projectDir = projectDir.replace('~', homedir());
+                }
+                projectDir = resolve(projectDir);
+            } else {
+                const channelConfig = getChannelConfigCached(interaction.channelId);
+                projectDir = channelConfig?.working_dir
+                    || process.env.CLAUDE_WORKING_DIR
+                    || process.cwd();
+            }
+
+            const limit = interaction.options.getInteger('limit') ?? 5;
+            const sessions = listSessions(projectDir, limit);
+
+            if (sessions.length === 0) {
+                await interaction.reply({
+                    content: `No Claude sessions found for \`${projectDir}\`.`,
+                    ephemeral: true,
+                });
+                return;
+            }
+
+            // Format session list
+            const lines = sessions.map((s, i) => {
+                const age = formatAge(s.lastActivity);
+                const preview = s.firstMessage
+                    ? s.firstMessage.slice(0, 80) + (s.firstMessage.length > 80 ? '…' : '')
+                    : '(no messages)';
+                return `**${i + 1}.** \`${s.id.slice(0, 8)}…\` — ${age} ago, ${s.messageCount} msgs\n> ${preview}`;
+            });
+
+            await interaction.reply({
+                content: `**Claude Sessions** for \`${projectDir}\`\n\n${lines.join('\n\n')}`,
+                ephemeral: true,
+            });
+            log(`Listed ${sessions.length} sessions for ${projectDir}`);
+        }
         return;
     }
 

package/src/config.ts

@@ -226,7 +226,11 @@ export function writeSecret(key: string, value: string, password: string): void
 
     let secrets: Record<string, string> = {};
     if (existsSync(getSecretsPath())) {
-        secrets = readSecrets(password);
+        try {
+            secrets = readSecrets(password);
+        } catch {
+            throw new Error('Wrong password. Use the same password you set previously, or delete ~/.config/tether/secrets.enc to start fresh.');
+        }
     }
 
     secrets[key] = value;
@@ -240,7 +244,12 @@ export function deleteKey(key: string, password?: string): boolean {
         if (!password) throw new Error('Password required to modify secrets');
         if (!existsSync(getSecretsPath())) return false;
 
-        const secrets = readSecrets(password);
+        let secrets: Record<string, string>;
+        try {
+            secrets = readSecrets(password);
+        } catch {
+            throw new Error('Wrong password. Use the same password you set previously.');
+        }
         if (!(key in secrets)) return false;
         delete secrets[key];
 

package/src/features/sessions.ts

@@ -0,0 +1,201 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export interface SessionInfo {
+  id: string;
+  createdAt: Date;
+  lastActivity: Date;
+  messageCount: number;
+  firstMessage: string;
+  cwd: string;
+}
+
+interface SessionLine {
+  type?: string;
+  sessionId?: string;
+  uuid?: string;
+  parentUuid?: string | null;
+  cwd?: string;
+  timestamp?: string;
+  message?: {
+    role?: string;
+    content?: string | Array<{ type: string; text?: string }>;
+  };
+}
+
+/**
+ * Convert a filesystem path to Claude's sanitized directory name.
+ * Claude replaces `/`, `\`, and `:` with `-`.
+ * 
+ * Examples:
+ * - macOS: `/Users/sam/project` → `-Users-sam-project`
+ * - Windows: `C:\Github\project` → `C--Github-project`
+ * - Linux: `/home/user/project` → `-home-user-project`
+ */
+export function sanitizePath(projectPath: string): string {
+  return projectPath.replace(/[/\\:]/g, '-');
+}
+
+/**
+ * Return the full path to Claude's sessions directory for a given project path.
+ */
+export function getSessionsDir(projectPath: string): string {
+  const sanitized = sanitizePath(projectPath);
+  return join(homedir(), '.claude', 'projects', sanitized);
+}
+
+/**
+ * Parse a JSONL session file and extract metadata.
+ * Returns null if the file doesn't exist, is empty, or cannot be parsed.
+ */
+export function parseSessionFile(filePath: string): SessionInfo | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf-8').trim();
+    if (!content) {
+      return null;
+    }
+
+    const lines = content.split('\n');
+    const messages: SessionLine[] = [];
+
+    // Parse each line, skipping corrupted ones
+    for (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const parsed = JSON.parse(line) as SessionLine;
+        messages.push(parsed);
+      } catch {
+        // Skip corrupted lines
+        continue;
+      }
+    }
+
+    if (messages.length === 0) {
+      return null;
+    }
+
+    // Extract metadata
+    const firstMsg = messages[0];
+    if (!firstMsg) {
+      return null;
+    }
+    const lastMsg = messages[messages.length - 1];
+    if (!lastMsg) {
+      return null;
+    }
+
+    // Get session ID
+    const sessionId = firstMsg.sessionId || firstMsg.uuid || 'unknown';
+
+    // Get CWD (usually from first message)
+    const cwd = firstMsg.cwd || '';
+
+    // Get timestamps
+    const createdAt = firstMsg.timestamp ? new Date(firstMsg.timestamp) : new Date(0);
+    const lastActivity = lastMsg.timestamp ? new Date(lastMsg.timestamp) : createdAt;
+
+    // Get first user message content
+    let firstMessage = '';
+    for (const msg of messages) {
+      if (msg.type === 'user' && msg.message?.content) {
+        const content = msg.message.content;
+        if (typeof content === 'string') {
+          firstMessage = content;
+        } else if (Array.isArray(content)) {
+          // Handle array of content blocks
+          const textBlock = content.find(block => block.type === 'text' && block.text);
+          if (textBlock && textBlock.text) {
+            firstMessage = textBlock.text;
+          }
+        }
+        break;
+      }
+    }
+
+    return {
+      id: sessionId,
+      createdAt,
+      lastActivity,
+      messageCount: messages.length,
+      firstMessage,
+      cwd,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all sessions for a project path, sorted by lastActivity descending.
+ * Returns empty array if the sessions directory doesn't exist.
+ */
+export function listSessions(projectPath: string, limit?: number): SessionInfo[] {
+  const sessionsDir = getSessionsDir(projectPath);
+
+  if (!existsSync(sessionsDir)) {
+    return [];
+  }
+
+  try {
+    const files = readdirSync(sessionsDir);
+    const jsonlFiles = files.filter(f => f.endsWith('.jsonl'));
+
+    const sessions: SessionInfo[] = [];
+
+    for (const file of jsonlFiles) {
+      const filePath = join(sessionsDir, file);
+      
+      // Skip if not a file
+      try {
+        const stats = statSync(filePath);
+        if (!stats.isFile()) {
+          continue;
+        }
+      } catch {
+        continue;
+      }
+
+      const session = parseSessionFile(filePath);
+      if (session) {
+        sessions.push(session);
+      }
+    }
+
+    // Sort by lastActivity descending (newest first)
+    sessions.sort((a, b) => b.lastActivity.getTime() - a.lastActivity.getTime());
+
+    // Apply limit if specified
+    if (limit !== undefined && limit > 0) {
+      return sessions.slice(0, limit);
+    }
+
+    return sessions;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Format a date as a human-readable relative time string.
+ * e.g. "2m", "3h", "1d", "2w"
+ */
+export function formatAge(date: Date): string {
+  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d`;
+  const weeks = Math.floor(days / 7);
+  return `${weeks}w`;
+}