residoo 0.1.0 → 0.3.0

package/src/sources/amazon-q.js

@@ -0,0 +1,199 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Amazon Q Developer — the AWS chat/coding-assistant IDE plugin (VS Code via
+ * the AWS Toolkit / "Amazon Q" extension, and the JetBrains "Amazon Q"
+ * plugin; formerly CodeWhisperer).
+ *
+ * VERIFICATION STATUS (read this before trusting anything below):
+ * multi-source-corroborated-but-UNVERIFIED against a real install. Neither VS
+ * Code, JetBrains, nor any Amazon Q plugin is installed on the machine this
+ * adapter was built on (checked: no /Applications/*Code*.app, no `code` on
+ * PATH, no `~/.aws/amazonq` directory — `~/.aws` itself exists here only from
+ * an old, unrelated AWS CLI credentials setup, `config`/`credentials` only,
+ * no `amazonq` subdirectory). What IS unusually strong here, short of a real
+ * install: the storage mechanism and exact filenames were read directly out
+ * of AWS's own current shipped source for BOTH clients, not inferred from a
+ * blog post:
+ *
+ *   1. `aws/aws-toolkit-vscode` (the VS Code client), `main` branch,
+ *      `packages/core/src/shared/db/chatDb/chatDb.ts`, fetched verbatim via
+ *      `gh api repos/aws/aws-toolkit-vscode/contents/...` on 2026-09-02 —
+ *      its own docstring states plainly: "The database is stored in the
+ *      user's home directory under .aws/amazonq/history with a unique
+ *      filename based on the workspace identifier," and the constructor
+ *      confirms it exactly:
+ *        `this.dbDirectory = path.join(fs.getUserHomeDir(), '.aws/amazonq/history')`
+ *        `const dbName = \`chat-history-${workspaceId}.json\``
+ *      where `getWorkspaceIdentifier()` (same file) is an MD5 hex hash of
+ *      the open `.code-workspace` path, or of the sorted+joined multi-root
+ *      folder paths, or of the single open folder path, or the literal
+ *      string `'no-workspace'` when nothing is open — i.e. filenames are
+ *      exactly `chat-history-<32-hex-md5>.json` or
+ *      `chat-history-no-workspace.json`. The "database" itself is LokiJS
+ *      (`import Loki from 'lokijs'`, `persistenceMethod: 'fs'`) — an
+ *      embedded JS document store that serializes its entire collection set
+ *      as ONE JSON document per file, not a real SQL database despite the
+ *      `.json`-suffixed "chat-history-" naming — so this is ordinary,
+ *      scannable JSON text on disk, no special binary/SQLite handling
+ *      needed (unlike cursor.js/cody.js).
+ *
+ *   2. `Amazon-Q-Developer/language-servers`,
+ *      `server/aws-lsp-codewhisperer/src/language-server/agenticChat/tools/chatDb/chatDb.ts`
+ *      — the SAME class, byte-for-byte the same docstring and
+ *      `.aws/amazonq/history` path, living in the shared "Flare" language
+ *      server package both IDE clients embed. Confirmed the JetBrains client
+ *      actually embeds this same language server (not a separate,
+ *      JetBrains-native storage layer) by reading
+ *      `Amazon-Q-Developer/amazon-q-jetbrains`,
+ *      `plugins/amazonq/shared/jetbrains-community/src/software/aws/toolkits/jetbrains/services/amazonq/lsp/AmazonQLanguageClientImpl.kt`
+ *      (same fetch method, same date) — the JetBrains plugin is an LSP
+ *      *client* to the identical CodeWhisperer/Q language server, so its chat
+ *      history lands in the exact same home-directory path as VS Code's,
+ *      not a JetBrains-specific config/plugins directory. This is why this
+ *      one adapter covers both IDEs with a single, IDE-agnostic path — no
+ *      per-editor branching needed, unlike copilot-chat.js/cody.js.
+ *
+ *   Independent, non-AWS corroboration of the same exact path and filename
+ *   pattern (cross-checked, all agree with each other and with the source
+ *   above): a real user's own write-up at
+ *   dev.to/aws/finding-and-recovering-your-amazon-q-developer-prompt-history-28j1
+ *   ("In the ~/.aws/amazonq/ directory there is a history directory... json
+ *   files" — names `chat-history-no-workspace.json` and several
+ *   `chat-history-<hash>.json` examples verbatim); a third-party forensics
+ *   tool, `ACandeias/AI-Forensicator`, `collectors/amazon_q.py`, whose own
+ *   comment reads "~/.aws/amazonq/history/  -- chat history JSON files"; and
+ *   a third-party agent-session spec, `YawLabs/ctxlint`,
+ *   `agent-session-lint-rules.json`, recording
+ *   `"historyLocation": "~/.aws/amazonq/history/chat-history-*.json"`.
+ *
+ * No per-OS path branching in the AWS source read above (`fs.getUserHomeDir()`
+ * joined with the same relative `.aws/amazonq/history` on every platform) —
+ * matching the long-standing, cross-platform AWS CLI/SDK convention of a
+ * single `~/.aws` (`%USERPROFILE%\.aws` on Windows) regardless of OS, unlike
+ * VS Code's own per-OS `Application Support`/`AppData`/XDG split that most
+ * other sources in this project have to branch on.
+ *
+ * Deliberately out of scope: any Amazon Q Developer usage OUTSIDE the IDE
+ * plugins covered here — the separate `q chat` CLI, the GitHub-hosted
+ * "Amazon Q Developer for GitHub" integration, and Kiro (a distinct AWS
+ * product that a third-party source above notes also happens to write into
+ * this same directory) are different products with their own storage
+ * questions, not verified here and not claimed by this adapter.
+ */
+function historyDir() {
+  return path.join(os.homedir(), ".aws", "amazonq", "history");
+}
+
+const HISTORY_DIR = historyDir();
+
+// Bounds for readLines() — same rationale and values as claude-code.js.
+// Not backed by a real chat-history-*.json file this tool was tested
+// against (no install to test with) — see the verification-status note
+// above. A LokiJS-serialized history file is a single JSON document, so in
+// practice this caps one very long "line," the same shape copilot-chat.js
+// already handles for a flat (non-JSONL) chat session snapshot.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+function id() { return "amazon-q"; }
+function label() { return "Amazon Q Developer"; }
+
+function available() {
+  try { return fs.statSync(HISTORY_DIR).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js's
+ * isKindFollowingSymlink — see that file's docstring for the full reasoning.
+ * Duplicated rather than imported, matching this project's "small,
+ * self-contained file" convention.
+ */
+function isKindFollowingSymlink(fullPath, dirent, checkFn) {
+  if (checkFn(dirent)) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return checkFn(fs.statSync(fullPath)); } catch { return false; }
+}
+const isFileFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isFile());
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every `chat-history-*.json`
+ * file directly inside `~/.aws/amazonq/history/` (flat, not recursive —
+ * `chatDb.ts`'s `dbDirectory` is the immediate parent of every db file, no
+ * further nesting per the source read above).
+ *
+ * Not filtered to the exact `chat-history-` prefix: `.aws/amazonq/history`
+ * is a directory this adapter treats as fully Amazon-Q-owned (per the
+ * source above, nothing else writes there), so any `*.json` found there is
+ * scanned — the same "don't hard-code a filename pattern likely to drift"
+ * caution cursor.js documents for its own key-name filtering, applied here
+ * to filenames instead of SQLite keys.
+ */
+function* files() {
+  let entries;
+  try { entries = fs.readdirSync(HISTORY_DIR, { withFileTypes: true }); }
+  catch { return; } // no history directory at all — Amazon Q never ran, or never opened chat
+
+  for (const e of entries) {
+    if (!e.name.endsWith(".json")) continue;
+    const file = path.join(HISTORY_DIR, e.name);
+    if (!isFileFollowingSymlink(file, e)) {
+      if (e.isSymbolicLink()) yield { file, broken: true };
+      continue;
+    }
+    let stat;
+    try { stat = fs.statSync(file); } catch { yield { file, broken: true }; continue; }
+    yield { file, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+/**
+ * Read one chat-history-*.json file as an array of raw text lines.
+ *
+ * Streamed line-by-line via readline/promises, same as claude-code.js and
+ * copilot-chat.js — LokiJS's `fs` persistence adapter writes its entire
+ * collection set as one JSON document (typically not pretty-printed), so in
+ * the common case this yields exactly one long "line," bounded by
+ * MAX_BYTES; if a given LokiJS version ever pretty-prints or the file
+ * otherwise contains embedded newlines, per-line scanning still works
+ * unchanged. Status vocabulary matches every other source in this project.
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  // Same rationale as claude-code.js: no natural timeout exists anywhere in
+  // Node's stream/readline stack, and a retargeted symlink can make the
+  // underlying open() block forever with no event ever firing.
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    // Whatever WAS read before the failure is real content and may contain
+    // a real secret — kept, not discarded, same as every other source here.
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };

package/src/sources/antigravity-cli.js

@@ -0,0 +1,155 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Google Antigravity (antigravity.google) — the agentic development platform
+ * Google launched at I/O 2026, whose CLI (built in Go, replacing Gemini CLI
+ * for agentic use) and desktop editor both write local session state under
+ * `~/.gemini/antigravity*`.
+ *
+ * VERIFICATION STATUS: corroborated by one detailed, credible source — NOT
+ * by two independent sources of the exact schema, and NOT checked against a
+ * real install on the machine this source was built on (no `~/.gemini`
+ * directory exists there; see CONTRIBUTING.md). Ship this with that
+ * explicitly weaker standing in mind relative to this project's other new
+ * sources.
+ *
+ * The source: jazzyalex/agent-sessions (github.com/jazzyalex/agent-sessions,
+ * 800+ stars) — a real, actively maintained macOS app built specifically to
+ * parse local AI-coding-agent session history for browsing/search — ships a
+ * dedicated guide page, "Antigravity CLI local history: transcripts and
+ * brain artifacts under `~/.gemini`," documenting (as this tool's own
+ * behavior, i.e. code the maintainer wrote and presumably ran against a real
+ * Antigravity install, not a secondhand description):
+ *   - CLI transcripts: `~/.gemini/antigravity-cli/brain/<conversation-id>/
+ *     .system_generated/logs/transcript.jsonl` (one step per line: fields
+ *     including step_index, source, type, status, created_at, content,
+ *     tool_calls, thinking, truncated_fields) plus a sibling
+ *     `transcript_full.jsonl` restoring content the primary file truncates.
+ *   - Editor artifacts: `~/.gemini/antigravity/brain/<conversation-id>/`
+ *     holding per-artifact Markdown (`task.md`, `implementation_plan.md`,
+ *     `walkthrough.md`, `proposal.md`) each paired with a `.metadata.json`.
+ *   - The same guide notes upgraded installs may also carry
+ *     `~/.gemini/antigravity-ide/brain` and `~/.gemini/antigravity-backup/
+ *     brain`, but says its own tool only scans the first two — this source
+ *     follows that same, narrower choice rather than guessing at the other
+ *     two directory names' internal shape.
+ *
+ * Real-world significance: Antigravity is a first-party Google product
+ * (Google I/O 2026 launch, "the only tool in this group not built on VS
+ * Code," free public preview with Gemini 3 Pro access as of that launch),
+ * so — schema-verification caveat above notwithstanding — this is exactly
+ * the kind of tool this project's coverage would be conspicuously incomplete
+ * without.
+ *
+ * This source walks both brain roots recursively for `.jsonl`, `.json`, and
+ * `.md` files (skipping the `.system_generated/logs` vs top-level distinction
+ * rather than hard-coding it) — the same "match by extension, don't pin the
+ * exact depth" tolerance claude-code.js applies to its own project-slug
+ * directories, since a screenshot or other binary asset the CLI writes
+ * alongside these would not match any of those three extensions anyway.
+ */
+const HOME = os.homedir();
+const GEMINI_DIR = path.join(HOME, ".gemini");
+const CLI_BRAIN_ROOT = path.join(GEMINI_DIR, "antigravity-cli", "brain");
+const EDITOR_BRAIN_ROOT = path.join(GEMINI_DIR, "antigravity", "brain");
+
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB — same backstop as claude-code.js.
+const READ_TIMEOUT_MS = 60_000;
+const MAX_WALK_DEPTH = 8;
+
+function id() { return "antigravity"; }
+function label() { return "Google Antigravity"; }
+
+function available() {
+  for (const root of [CLI_BRAIN_ROOT, EDITOR_BRAIN_ROOT]) {
+    try { if (fs.statSync(root).isDirectory()) return true; } catch { /* try the next root */ }
+  }
+  return false;
+}
+
+/**
+ * Same defensive symlink-following helpers as claude-code.js — see that
+ * file's docstring. Duplicated rather than imported, per this project's
+ * self-contained-source-file convention (see cursor.js's docstring).
+ */
+function isKindFollowingSymlink(fullPath, dirent, checkFn) {
+  if (checkFn(dirent)) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return checkFn(fs.statSync(fullPath)); } catch { return false; }
+}
+const isDirFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isDirectory());
+const isFileFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isFile());
+
+const TEXT_EXTENSIONS = new Set([".jsonl", ".json", ".md"]);
+
+/**
+ * Recursively yield { file, mtimeMs, sizeBytes, broken } for every plain
+ * text-like (see TEXT_EXTENSIONS) file under `dir` — see factory-droid.js's
+ * walk() for the identical symlink-handling reasoning.
+ */
+function* walk(dir, depth) {
+  if (depth > MAX_WALK_DEPTH) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (isDirFollowingSymlink(full, e)) {
+      yield* walk(full, depth + 1);
+      continue;
+    }
+    const isFile = isFileFollowingSymlink(full, e);
+    if (!isFile) {
+      if (e.isSymbolicLink()) yield { file: full, broken: true };
+      continue;
+    }
+    if (!TEXT_EXTENSIONS.has(path.extname(e.name))) continue; // e.g. a captured screenshot — out of scope
+    let stat;
+    try { stat = fs.statSync(full); } catch { yield { file: full, broken: true }; continue; }
+    yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+function* files() {
+  yield* walk(CLI_BRAIN_ROOT, 0);
+  yield* walk(EDITOR_BRAIN_ROOT, 0);
+}
+
+/**
+ * Read one transcript/artifact file as raw text lines. Identical streaming/
+ * timeout/partial-read discipline to claude-code.js's readLines().
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1;
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };

package/src/sources/cline.js

@@ -0,0 +1,208 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Cline (VS Code extension, historically shipped as "Claude Dev") session
+ * history.
+ *
+ * VERIFICATION STATUS: the path and file layout below were read directly out
+ * of Cline's own current source on GitHub (cline/cline) during this source's
+ * research — not inferred from a blog post and not guessed from Roo Code's
+ * near-identical fork, even though the two are in fact near-identical.
+ * Specifically:
+ *   - apps/vscode/src/core/storage/disk.ts — GlobalFileNames constants and
+ *     ensureTaskDirectoryExists()/getGlobalStorageDir(), which resolve
+ *     through the VS Code extension's own `globalStorageUri` (NOT
+ *     workspaceStorage) into `tasks/<taskId>/`.
+ *   - apps/vscode/package.json — `"name": "claude-dev"`, `"publisher":
+ *     "saoudrizwan"`, confirming the on-disk globalStorage folder is really
+ *     still `saoudrizwan.claude-dev` (Cline shipped as "Claude Dev" and kept
+ *     its original package.json identity across the product's later rename
+ *     to Cline — this is NOT the same as the current "Cline" display name,
+ *     and guessing `cline.cline` or similar would have been wrong).
+ * What this could NOT be checked against: a real Cline install on the
+ * machine this source was built on — VS Code itself isn't installed there.
+ * See CONTRIBUTING.md for what "verified" is supposed to mean and treat
+ * findings from this source accordingly until someone with Cline actually
+ * installed confirms it against real data.
+ *
+ * Cline writes one JSON file per concern into a per-task directory under its
+ * extension's VS Code globalStorage folder:
+ *
+ *   <VS Code User dir>/globalStorage/saoudrizwan.claude-dev/tasks/<taskId>/
+ *     api_conversation_history.json   - full message history sent to the model
+ *     ui_messages.json                - the rendered chat transcript
+ *     context_history.json            - context-window bookkeeping
+ *     task_metadata.json              - files touched, model/token usage
+ *     settings.json                   - a per-task settings snapshot
+ *
+ * Filenames are deliberately NOT allow-listed beyond "every *.json file
+ * directly inside tasks/<taskId>/": GlobalFileNames in Cline's own source has
+ * gained entries over time (context_history.json is a relatively recent
+ * addition) and hard-coding today's list is exactly the kind of thing likely
+ * to go stale the same way cursor.js's docstring describes for Cursor's own
+ * key names. A task's `checkpoints/` subdirectory (shadow-git snapshots used
+ * for file revert) is deliberately NOT walked — those are git object stores,
+ * not text transcripts.
+ *
+ * Base directory: VS Code has a portable/remote/Insiders/fork multiverse of
+ * possible per-profile "User" directories. This source checks the two by far
+ * most common ones on each OS — standard VS Code ("Code") and VS Code
+ * Insiders ("Code - Insiders") — and deliberately does NOT attempt every
+ * fork (VSCodium, etc.) or the separate ~/.vscode-server tree used by
+ * remote-SSH sessions: a named, narrower scope rather than a guess at an
+ * exhaustive list.
+ *
+ * Also out of scope, named rather than silently skipped: Cline's task-title
+ * history INDEX (the array a "History" panel is built from) is not a plain
+ * file — it is read via VS Code's own `context.globalState` API, which
+ * persists into a *different*, central per-profile database
+ * (globalStorage/state.vscdb, shared by every installed extension, keyed by
+ * extension id) rather than anywhere under this extension's own
+ * globalStorage folder. Parsing that shared, VS-Code-owned database is out of
+ * scope for this source; the per-task JSON files above are where actual
+ * conversation content — and anything pasted into it — lives.
+ */
+const EXT_ID = "saoudrizwan.claude-dev";
+
+function vscodeUserDirs() {
+  const home = os.homedir();
+  const variants = ["Code", "Code - Insiders"];
+  if (process.platform === "darwin") {
+    return variants.map((v) => path.join(home, "Library", "Application Support", v, "User"));
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return variants.map((v) => path.join(appData, v, "User"));
+  }
+  // Linux and other XDG-following unix platforms.
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return variants.map((v) => path.join(configHome, v, "User"));
+}
+
+function tasksDirs() {
+  return vscodeUserDirs().map((userDir) => path.join(userDir, "globalStorage", EXT_ID, "tasks"));
+}
+
+// Bounds for readLines() — same rationale and same values as claude-code.js:
+// generous headroom over any real transcript, plus a hard stop against a
+// hung read. Not backed by a real Cline transcript this tool was tested
+// against (no install to test with) — see the verification-status note above.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+function id() { return "cline"; }
+function label() { return "Cline"; }
+
+function available() {
+  return tasksDirs().some((dir) => {
+    try { return fs.statSync(dir).isDirectory(); } catch { return false; }
+  });
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js's
+ * isDirFollowingSymlink/isFileFollowingSymlink — see that file's docstring
+ * for the full reasoning. Duplicated rather than imported: each source in
+ * this project is meant to be a small, self-contained file a reviewer can
+ * audit on its own (see CONTRIBUTING.md and cursor.js's own note on this).
+ */
+function isKindFollowingSymlink(fullPath, dirent, checkFn) {
+  if (checkFn(dirent)) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return checkFn(fs.statSync(fullPath)); } catch { return false; }
+}
+const isDirFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isDirectory());
+const isFileFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isFile());
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every *.json file directly
+ * inside every task directory, across every candidate VS Code User dir.
+ *
+ * broken:true marks a tasks/ entry or a *.json entry that looked like it
+ * should resolve (chiefly a dangling symlink) but didn't — never silently
+ * skipped, same convention as claude-code.js and cursor.js.
+ */
+function* files() {
+  for (const tasksDir of tasksDirs()) {
+    let taskEntries;
+    try { taskEntries = fs.readdirSync(tasksDir, { withFileTypes: true }); }
+    catch { continue; } // this VS Code variant/profile simply has no Cline tasks dir — normal, not broken
+
+    for (const taskEntry of taskEntries) {
+      const taskDir = path.join(tasksDir, taskEntry.name);
+      if (!isDirFollowingSymlink(taskDir, taskEntry)) {
+        if (taskEntry.isSymbolicLink()) yield { file: taskDir, broken: true };
+        continue; // a stray non-directory entry under tasks/ is out of scope, not broken
+      }
+
+      let fileEntries;
+      try { fileEntries = fs.readdirSync(taskDir, { withFileTypes: true }); }
+      catch { yield { file: taskDir, broken: true }; continue; }
+
+      for (const e of fileEntries) {
+        if (!e.name.endsWith(".json")) continue;
+        const file = path.join(taskDir, e.name);
+        if (!isFileFollowingSymlink(file, e)) {
+          if (e.isSymbolicLink()) yield { file, broken: true };
+          continue;
+        }
+        let stat;
+        try { stat = fs.statSync(file); } catch { yield { file, broken: true }; continue; }
+        yield { file, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+      }
+    }
+  }
+}
+
+/**
+ * Read one JSON file as an array of raw text lines.
+ *
+ * Cline writes these via `JSON.stringify(value, null, 2)` (confirmed from
+ * disk.ts) — real multi-line, indented text, not a single giant line — so
+ * the same streamed readline/promises approach claude-code.js uses for JSONL
+ * applies here essentially unchanged, and gets the same benefits: no
+ * whole-file-as-one-string V8 string-length ceiling, and a partial read (the
+ * file started streaming but the read failed partway) still returns
+ * whatever lines WERE read rather than discarding real content.
+ *
+ * Status vocabulary matches every other source in this project: "complete",
+ * "partial", "too-large", "failed".
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  // Same rationale as claude-code.js: no natural timeout exists anywhere in
+  // Node's stream/readline stack, and a retargeted symlink can make the
+  // underlying open() block forever with no event ever firing. Destroying
+  // the stream is what actually unblocks that.
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };