From 0a939a14dabb3d6afbf17d5da08c6d4b863bd99f Mon Sep 17 00:00:00 2001
From: Rhuan Barreto <rhuan@barreto.work>
Date: Tue, 5 May 2026 21:59:03 +0200
Subject: [PATCH 1/2] feat: add session-context support for Copilot CLI and
 opencode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend the `session-context` command with two new subcommands:

- `session-context copilot` — reads Copilot CLI session transcripts
  from `~/.copilot/session-state/`, matching sessions by workspace
  `cwd` field via `workspace.yaml` + `events.jsonl`
- `session-context opencode` — reads opencode session transcripts from
  `~/.local/share/opencode/storage/`, matching sessions by project
  `path` field in session metadata + individual message JSON files

Both support `--max-entries` and `--session-id` options, following the
existing Cursor subcommand pattern.

Also:
- Add `copilotSessionStateDir()` and `opencodeStorageDir()` path helpers
- Export shared utilities (TranscriptEntry, getContentPreview, RELEVANT_ROLES)
  from session-context.ts for reuse by per-editor reader modules
- Split new readers into separate files to stay under max-lines lint rule
- Update EN and pt-br reference docs with new subcommand sections

Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
---
 .../agent-memory/archgate-developer/MEMORY.md |   1 +
 .../pt-br/reference/cli/session-context.mdx   |  38 +++
 .../docs/reference/cli/session-context.mdx    |  38 +++
 src/commands/session-context/copilot.ts       |  41 +++
 src/commands/session-context/index.ts         |   4 +
 src/commands/session-context/opencode.ts      |  41 +++
 src/helpers/paths.ts                          |  31 +++
 src/helpers/session-context-copilot.ts        | 171 ++++++++++++
 src/helpers/session-context-opencode.ts       | 225 ++++++++++++++++
 src/helpers/session-context.ts                |   6 +-
 tests/commands/session-context.test.ts        |  44 +++
 .../commands/session-context/copilot.test.ts  |  37 +++
 .../commands/session-context/opencode.test.ts |  37 +++
 tests/helpers/session-context-copilot.test.ts | 251 ++++++++++++++++++
 .../helpers/session-context-opencode.test.ts  | 241 +++++++++++++++++
 15 files changed, 1203 insertions(+), 3 deletions(-)
 create mode 100644 src/commands/session-context/copilot.ts
 create mode 100644 src/commands/session-context/opencode.ts
 create mode 100644 src/helpers/session-context-copilot.ts
 create mode 100644 src/helpers/session-context-opencode.ts
 create mode 100644 tests/commands/session-context/copilot.test.ts
 create mode 100644 tests/commands/session-context/opencode.test.ts
 create mode 100644 tests/helpers/session-context-copilot.test.ts
 create mode 100644 tests/helpers/session-context-opencode.test.ts

diff --git a/.claude/agent-memory/archgate-developer/MEMORY.md b/.claude/agent-memory/archgate-developer/MEMORY.md
index 6b1e1c0e..ddf269fb 100644
--- a/.claude/agent-memory/archgate-developer/MEMORY.md
+++ b/.claude/agent-memory/archgate-developer/MEMORY.md
@@ -30,6 +30,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 
 ## Patterns & Fixes
 
+- **YAML double-quoted strings require escaped backslashes for Windows paths in tests** — YAML interprets `\` as an escape character inside double-quoted strings. Writing `cwd: "E:\project"` silently corrupts the parsed value because `\p` is not a valid escape sequence. Fix: use `JSON.stringify(path)` to produce properly escaped YAML values (e.g., `cwd: ${JSON.stringify(cwd)}`). JSON and YAML double-quoted strings share the same escape syntax. Encountered in Copilot CLI session-context tests (`workspace.yaml` with Windows paths).
 - **`git commit` in temp repos requires local identity** — CI runners have no global `user.email`/`user.name` configured. Any test that runs `git commit` on a temp repo MUST call `git config user.email` and `git config user.name` locally after `git init`. Fails with a cryptic `ShellPromise` error in CI; passes locally. Also captured in ARCH-005 Do's.
 - **Never use `bunx prettier` directly** — Always use `bun run format` (to fix) or `bun run format:check` (to verify). Using `bunx prettier` can fail or use a different version than the project's devDependency. The same applies to all dev tools: prefer `bun run <script>` over `bunx <tool>` when a package.json script exists.
 - **`Bun.Glob.match()` triggers oxlint `prefer-regexp-test`** — `Bun.Glob.match()` returns a boolean (not a RegExp), but oxlint can't tell. Suppress with `// oxlint-disable-next-line prefer-regexp-test -- Bun.Glob.match() returns boolean, not RegExp`.
diff --git a/docs/src/content/docs/pt-br/reference/cli/session-context.mdx b/docs/src/content/docs/pt-br/reference/cli/session-context.mdx
index b6f0fab5..88a14092 100644
--- a/docs/src/content/docs/pt-br/reference/cli/session-context.mdx
+++ b/docs/src/content/docs/pt-br/reference/cli/session-context.mdx
@@ -23,6 +23,19 @@ archgate session-context claude-code [options]
 | ------------------- | ------------------------------------------- |
 | `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
 
+### archgate session-context copilot
+
+Lê a transcrição de sessão do Copilot CLI para o projeto. Sessões são correspondidas pelo campo `cwd` do workspace.
+
+```bash
+archgate session-context copilot [options]
+```
+
+| Opção               | Descrição                                   |
+| ------------------- | ------------------------------------------- |
+| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
+| `--session-id <id>` | UUID específico da sessão a ser lida        |
+
 ### archgate session-context cursor
 
 Lê a transcrição de sessão do agente Cursor para o projeto.
@@ -36,6 +49,19 @@ archgate session-context cursor [options]
 | `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
 | `--session-id <id>` | UUID específico da sessão a ser lida        |
 
+### archgate session-context opencode
+
+Lê a transcrição de sessão do opencode para o projeto. Sessões são correspondidas pelo campo `path` do projeto nos metadados da sessão.
+
+```bash
+archgate session-context opencode [options]
+```
+
+| Opção               | Descrição                                   |
+| ------------------- | ------------------------------------------- |
+| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
+| `--session-id <id>` | ID específico da sessão a ser lida          |
+
 ## Exemplos
 
 Ler a última sessão do Claude Code:
@@ -49,3 +75,15 @@ Ler uma sessão específica do Cursor:
 ```bash
 archgate session-context cursor --session-id abc123
 ```
+
+Ler a última sessão do Copilot CLI:
+
+```bash
+archgate session-context copilot
+```
+
+Ler a última sessão do opencode:
+
+```bash
+archgate session-context opencode
+```
diff --git a/docs/src/content/docs/reference/cli/session-context.mdx b/docs/src/content/docs/reference/cli/session-context.mdx
index cc33f658..62a31e8e 100644
--- a/docs/src/content/docs/reference/cli/session-context.mdx
+++ b/docs/src/content/docs/reference/cli/session-context.mdx
@@ -23,6 +23,19 @@ archgate session-context claude-code [options]
 | ------------------- | ---------------------------------------- |
 | `--max-entries <n>` | Maximum entries to return (default: 200) |
 
+### archgate session-context copilot
+
+Read the Copilot CLI session transcript for the project. Sessions are matched by their workspace `cwd` field.
+
+```bash
+archgate session-context copilot [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+| `--session-id <id>` | Specific session UUID to read            |
+
 ### archgate session-context cursor
 
 Read the Cursor agent session transcript for the project.
@@ -36,6 +49,19 @@ archgate session-context cursor [options]
 | `--max-entries <n>` | Maximum entries to return (default: 200) |
 | `--session-id <id>` | Specific session UUID to read            |
 
+### archgate session-context opencode
+
+Read the opencode session transcript for the project. Sessions are matched by the project `path` field in session metadata.
+
+```bash
+archgate session-context opencode [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+| `--session-id <id>` | Specific session ID to read              |
+
 ## Examples
 
 Read the latest Claude Code session:
@@ -49,3 +75,15 @@ Read a specific Cursor session:
 ```bash
 archgate session-context cursor --session-id abc123
 ```
+
+Read the latest Copilot CLI session:
+
+```bash
+archgate session-context copilot
+```
+
+Read the latest opencode session:
+
+```bash
+archgate session-context opencode
+```
diff --git a/src/commands/session-context/copilot.ts b/src/commands/session-context/copilot.ts
new file mode 100644
index 00000000..9212c061
--- /dev/null
+++ b/src/commands/session-context/copilot.ts
@@ -0,0 +1,41 @@
+import type { Command } from "@commander-js/extra-typings";
+import { Option } from "@commander-js/extra-typings";
+
+import { exitWith } from "../../helpers/exit";
+import { logError } from "../../helpers/log";
+import { formatJSON } from "../../helpers/output";
+import { findProjectRoot } from "../../helpers/paths";
+import { readCopilotSession } from "../../helpers/session-context-copilot";
+
+const maxEntriesOption = new Option(
+  "--max-entries <n>",
+  "maximum entries to return (default: 200)"
+).argParser((val) => parseInt(val, 10));
+
+export function registerCopilotSessionContextCommand(parent: Command) {
+  parent
+    .command("copilot")
+    .description("Read Copilot CLI session transcript for the project")
+    .addOption(maxEntriesOption)
+    .option("--session-id <id>", "Specific session UUID to read")
+    .action(async (opts) => {
+      try {
+        const projectRoot = findProjectRoot();
+        const result = await readCopilotSession(projectRoot, {
+          maxEntries: opts.maxEntries,
+          sessionId: opts.sessionId,
+        });
+
+        if (!result.ok) {
+          logError(result.error);
+          await exitWith(1);
+          return;
+        }
+
+        console.log(formatJSON(result.data));
+      } catch (err) {
+        logError(err instanceof Error ? err.message : String(err));
+        await exitWith(1);
+      }
+    });
+}
diff --git a/src/commands/session-context/index.ts b/src/commands/session-context/index.ts
index 1ad8662f..da14d7cc 100644
--- a/src/commands/session-context/index.ts
+++ b/src/commands/session-context/index.ts
@@ -1,7 +1,9 @@
 import type { Command } from "@commander-js/extra-typings";
 
 import { registerClaudeCodeSessionContextCommand } from "./claude-code";
+import { registerCopilotSessionContextCommand } from "./copilot";
 import { registerCursorSessionContextCommand } from "./cursor";
+import { registerOpencodeSessionContextCommand } from "./opencode";
 
 export function registerSessionContextCommand(program: Command) {
   const sessionContext = program
@@ -9,5 +11,7 @@ export function registerSessionContextCommand(program: Command) {
     .description("Read AI editor session transcripts");
 
   registerClaudeCodeSessionContextCommand(sessionContext);
+  registerCopilotSessionContextCommand(sessionContext);
   registerCursorSessionContextCommand(sessionContext);
+  registerOpencodeSessionContextCommand(sessionContext);
 }
diff --git a/src/commands/session-context/opencode.ts b/src/commands/session-context/opencode.ts
new file mode 100644
index 00000000..088c300c
--- /dev/null
+++ b/src/commands/session-context/opencode.ts
@@ -0,0 +1,41 @@
+import type { Command } from "@commander-js/extra-typings";
+import { Option } from "@commander-js/extra-typings";
+
+import { exitWith } from "../../helpers/exit";
+import { logError } from "../../helpers/log";
+import { formatJSON } from "../../helpers/output";
+import { findProjectRoot } from "../../helpers/paths";
+import { readOpencodeSession } from "../../helpers/session-context-opencode";
+
+const maxEntriesOption = new Option(
+  "--max-entries <n>",
+  "maximum entries to return (default: 200)"
+).argParser((val) => parseInt(val, 10));
+
+export function registerOpencodeSessionContextCommand(parent: Command) {
+  parent
+    .command("opencode")
+    .description("Read opencode session transcript for the project")
+    .addOption(maxEntriesOption)
+    .option("--session-id <id>", "Specific session ID to read")
+    .action(async (opts) => {
+      try {
+        const projectRoot = findProjectRoot();
+        const result = await readOpencodeSession(projectRoot, {
+          maxEntries: opts.maxEntries,
+          sessionId: opts.sessionId,
+        });
+
+        if (!result.ok) {
+          logError(result.error);
+          await exitWith(1);
+          return;
+        }
+
+        console.log(formatJSON(result.data));
+      } catch (err) {
+        logError(err instanceof Error ? err.message : String(err));
+        await exitWith(1);
+      }
+    });
+}
diff --git a/src/helpers/paths.ts b/src/helpers/paths.ts
index 7fc8eddf..505a96ff 100644
--- a/src/helpers/paths.ts
+++ b/src/helpers/paths.ts
@@ -57,6 +57,37 @@ export function opencodeAgentsDir(): string {
   return join(base, "opencode", "agents");
 }
 
+/**
+ * Resolve the Copilot CLI session-state directory.
+ *
+ * Copilot CLI stores session data (workspace.yaml + events.jsonl) under
+ * `~/.copilot/session-state/<session-uuid>/`. Each session directory
+ * contains a `workspace.yaml` with a `cwd` field for project matching.
+ *
+ * Resolved at call time (not cached) so tests can override HOME.
+ */
+export function copilotSessionStateDir(): string {
+  return join(archgateHomeDir(), ".copilot", "session-state");
+}
+
+/**
+ * Resolve the opencode data storage directory.
+ *
+ * Opencode stores sessions, messages, and parts under
+ * `$XDG_DATA_HOME/opencode/storage/` (defaulting to
+ * `~/.local/share/opencode/storage/`). This is distinct from the
+ * config directory (`$XDG_CONFIG_HOME/opencode/`) used by
+ * `opencodeAgentsDir()`.
+ *
+ * Resolved at call time (not cached) so tests can override HOME /
+ * XDG_DATA_HOME.
+ */
+export function opencodeStorageDir(): string {
+  const xdg = usableEnv(Bun.env.XDG_DATA_HOME);
+  const base = xdg ?? join(archgateHomeDir(), ".local", "share");
+  return join(base, "opencode", "storage");
+}
+
 export const paths = { cacheFolder: internalPath("cache") } as const;
 
 export function projectPath(projectRoot: string, ...path: string[]) {
diff --git a/src/helpers/session-context-copilot.ts b/src/helpers/session-context-copilot.ts
new file mode 100644
index 00000000..35ad665c
--- /dev/null
+++ b/src/helpers/session-context-copilot.ts
@@ -0,0 +1,171 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { logDebug } from "./log";
+import { copilotSessionStateDir } from "./paths";
+import { isWindows } from "./platform";
+import {
+  type ReadSessionOptions,
+  type TranscriptEntry,
+  getContentPreview,
+} from "./session-context";
+
+export interface CopilotSessionSummary {
+  sessionId: string;
+  sessionFile: string;
+  totalEntries: number;
+  relevantEntries: number;
+  transcript: Array<{ role: string; contentPreview: string }>;
+}
+
+export interface ReadCopilotSessionOptions extends ReadSessionOptions {
+  sessionId?: string;
+}
+
+type CopilotSessionResult =
+  | { ok: true; data: CopilotSessionSummary }
+  | { ok: false; error: string; path?: string; available?: string[] };
+
+/**
+ * Normalize a file path for cross-platform comparison.
+ * Lowercases on Windows (case-insensitive FS), normalizes separators to `/`,
+ * and resolves to an absolute path.
+ */
+function normalizePath(p: string): string {
+  const resolved = resolve(p).replaceAll("\\", "/");
+  return isWindows() ? resolved.toLowerCase() : resolved;
+}
+
+const COPILOT_RELEVANT_TYPES = new Set(["user.message", "assistant.message"]);
+
+/**
+ * Read a Copilot CLI session transcript for a project.
+ *
+ * Copilot CLI stores sessions under `~/.copilot/session-state/<uuid>/`.
+ * Each session directory contains:
+ * - `workspace.yaml` — metadata with a `cwd` field for project matching
+ * - `events.jsonl`   — JSONL event log with conversation events
+ *
+ * Sessions are matched by comparing the `cwd` field in workspace.yaml
+ * to the provided project root.
+ */
+export async function readCopilotSession(
+  projectRoot: string | null,
+  options?: ReadCopilotSessionOptions
+): Promise<CopilotSessionResult> {
+  const limit = options?.maxEntries ?? 200;
+  const stateDir = copilotSessionStateDir();
+  const normalizedProjectRoot = normalizePath(projectRoot ?? process.cwd());
+
+  // 1. List all session UUID directories
+  let allDirs: Array<{ name: string; mtime: number }>;
+  try {
+    allDirs = readdirSync(stateDir)
+      .map((name) => {
+        const fullPath = join(stateDir, name);
+        try {
+          const stat = statSync(fullPath);
+          return stat.isDirectory() ? { name, mtime: stat.mtimeMs } : null;
+        } catch {
+          return null;
+        }
+      })
+      .filter((d): d is { name: string; mtime: number } => d !== null)
+      .sort((a, b) => b.mtime - a.mtime);
+  } catch {
+    return {
+      ok: false,
+      error: "No Copilot CLI session-state directory found",
+      path: stateDir,
+    };
+  }
+
+  if (allDirs.length === 0) {
+    return { ok: false, error: "No session directories found", path: stateDir };
+  }
+
+  // 2. Parse workspace.yaml for each session to match by cwd
+  interface SessionMatch {
+    name: string;
+    mtime: number;
+  }
+  const matching: SessionMatch[] = [];
+  const allSessionIds: string[] = [];
+
+  for (const dir of allDirs) {
+    allSessionIds.push(dir.name);
+    const yamlPath = join(stateDir, dir.name, "workspace.yaml");
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- sequential read needed: each session's YAML determines project match
+      const raw = await Bun.file(yamlPath).text();
+      const meta = Bun.YAML.parse(raw) as Record<string, unknown>;
+      const cwd = typeof meta.cwd === "string" ? meta.cwd : null;
+      if (cwd && normalizePath(cwd) === normalizedProjectRoot) {
+        matching.push({ name: dir.name, mtime: dir.mtime });
+      }
+    } catch {
+      logDebug(`Skipping session ${dir.name}: cannot read workspace.yaml`);
+    }
+  }
+
+  if (matching.length === 0) {
+    return {
+      ok: false,
+      error: "No Copilot CLI sessions found for this project",
+      path: stateDir,
+      available: allSessionIds,
+    };
+  }
+
+  // 3. Select session by ID or most recent
+  const target = options?.sessionId
+    ? matching.find((s) => s.name === options.sessionId)
+    : matching[0];
+
+  if (!target) {
+    return {
+      ok: false,
+      error: `Session not found: ${options?.sessionId}`,
+      available: matching.map((s) => s.name),
+    };
+  }
+
+  // 4. Read events.jsonl
+  const eventsFile = join(stateDir, target.name, "events.jsonl");
+  let rawEntries: Array<Record<string, unknown>>;
+  try {
+    const raw = await Bun.file(eventsFile).text();
+    rawEntries = Bun.JSONL.parse(raw) as Array<Record<string, unknown>>;
+  } catch {
+    return {
+      ok: false,
+      error: "Session exists but has no conversation transcript",
+      path: eventsFile,
+    };
+  }
+
+  // 5. Filter to user/assistant events and normalize to TranscriptEntry shape
+  const relevant: CopilotSessionSummary["transcript"] = [];
+  for (const event of rawEntries) {
+    const eventType = String(event.type ?? "");
+    if (!COPILOT_RELEVANT_TYPES.has(eventType)) continue;
+    const role = eventType === "user.message" ? "user" : "assistant";
+    // Normalize to TranscriptEntry shape so getContentPreview works
+    const normalized: TranscriptEntry = {
+      message: { content: (event.data as Record<string, unknown>)?.content },
+    };
+    relevant.push({ role, contentPreview: getContentPreview(normalized) });
+  }
+
+  const trimmed = relevant.length > limit ? relevant.slice(-limit) : relevant;
+  return {
+    ok: true,
+    data: {
+      sessionId: target.name,
+      sessionFile: "events.jsonl",
+      totalEntries: rawEntries.length,
+      relevantEntries: relevant.length,
+      transcript: trimmed,
+    },
+  };
+}
diff --git a/src/helpers/session-context-opencode.ts b/src/helpers/session-context-opencode.ts
new file mode 100644
index 00000000..64cb131b
--- /dev/null
+++ b/src/helpers/session-context-opencode.ts
@@ -0,0 +1,225 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { logDebug } from "./log";
+import { opencodeStorageDir } from "./paths";
+import { isWindows } from "./platform";
+import {
+  RELEVANT_ROLES,
+  type ReadSessionOptions,
+  type TranscriptEntry,
+  getContentPreview,
+} from "./session-context";
+
+export interface OpencodeSessionSummary {
+  sessionId: string;
+  totalEntries: number;
+  relevantEntries: number;
+  transcript: Array<{ role: string; contentPreview: string }>;
+}
+
+export interface ReadOpencodeSessionOptions extends ReadSessionOptions {
+  sessionId?: string;
+}
+
+type OpencodeSessionResult =
+  | { ok: true; data: OpencodeSessionSummary }
+  | { ok: false; error: string; path?: string; available?: string[] };
+
+/**
+ * Normalize a file path for cross-platform comparison.
+ * Lowercases on Windows (case-insensitive FS), normalizes separators to `/`,
+ * and resolves to an absolute path.
+ */
+function normalizePath(p: string): string {
+  const resolved = resolve(p).replaceAll("\\", "/");
+  return isWindows() ? resolved.toLowerCase() : resolved;
+}
+
+interface SessionMeta {
+  id: string;
+  path: string;
+  updatedAt: number;
+  projectHash: string;
+}
+
+/**
+ * Read an opencode session transcript for a project.
+ *
+ * Opencode stores data under `~/.local/share/opencode/storage/`:
+ * - `session/<projectHash>/<sessionID>.json` — session metadata
+ * - `message/<sessionID>/<messageID>.json`   — individual messages
+ *
+ * Sessions are matched by comparing the `path` field in session metadata
+ * to the provided project root.
+ */
+export async function readOpencodeSession(
+  projectRoot: string | null,
+  options?: ReadOpencodeSessionOptions
+): Promise<OpencodeSessionResult> {
+  const limit = options?.maxEntries ?? 200;
+  const storageDir = opencodeStorageDir();
+  const sessionsRoot = join(storageDir, "session");
+  const normalizedProjectRoot = normalizePath(projectRoot ?? process.cwd());
+
+  // 1. Scan session/<projectHash>/ directories for session JSON files
+  const allSessions: SessionMeta[] = [];
+
+  let projectHashDirs: string[];
+  try {
+    projectHashDirs = readdirSync(sessionsRoot).filter((name) => {
+      try {
+        return statSync(join(sessionsRoot, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return {
+      ok: false,
+      error: "No opencode session storage found",
+      path: sessionsRoot,
+    };
+  }
+
+  for (const hashDir of projectHashDirs) {
+    const hashPath = join(sessionsRoot, hashDir);
+    let sessionFiles: string[];
+    try {
+      sessionFiles = readdirSync(hashPath).filter((f) => f.endsWith(".json"));
+    } catch {
+      continue;
+    }
+
+    for (const file of sessionFiles) {
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- sequential read needed: each session file determines project match
+        const raw = await Bun.file(join(hashPath, file)).json();
+        const meta = raw as Record<string, unknown>;
+        const id = typeof meta.id === "string" ? meta.id : null;
+        const sessionPath = typeof meta.path === "string" ? meta.path : null;
+        if (!id) continue;
+        // Parse updated_at — may be ISO string or camelCase variant
+        let updatedAt = 0;
+        if (typeof meta.updated_at === "string") {
+          updatedAt = new Date(meta.updated_at).getTime();
+        } else if (typeof meta.updatedAt === "string") {
+          updatedAt = new Date(meta.updatedAt as string).getTime();
+        } else if (typeof meta.updated_at === "number") {
+          updatedAt = meta.updated_at;
+        }
+
+        allSessions.push({
+          id,
+          path: sessionPath ?? "",
+          updatedAt,
+          projectHash: hashDir,
+        });
+      } catch {
+        logDebug(`Skipping session file ${file}: parse error`);
+      }
+    }
+  }
+
+  if (allSessions.length === 0) {
+    return {
+      ok: false,
+      error: "No opencode sessions found",
+      path: sessionsRoot,
+    };
+  }
+
+  // 2. Filter sessions by project path
+  const matching = allSessions
+    .filter((s) => s.path && normalizePath(s.path) === normalizedProjectRoot)
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+
+  if (matching.length === 0) {
+    return {
+      ok: false,
+      error: "No opencode sessions found for this project",
+      path: sessionsRoot,
+      available: allSessions.map((s) => s.id),
+    };
+  }
+
+  // 3. Select session by ID or most recent
+  const target = options?.sessionId
+    ? matching.find((s) => s.id === options.sessionId)
+    : matching[0];
+
+  if (!target) {
+    return {
+      ok: false,
+      error: `Session not found: ${options?.sessionId}`,
+      available: matching.map((s) => s.id),
+    };
+  }
+
+  // 4. Read message files from message/<sessionID>/
+  const messagesDir = join(storageDir, "message", target.id);
+  let messageFiles: string[];
+  try {
+    messageFiles = readdirSync(messagesDir)
+      .filter((f) => f.endsWith(".json"))
+      .sort(); // Lexicographic sort — message IDs are ordered
+  } catch {
+    return {
+      ok: false,
+      error: "Session exists but has no messages",
+      path: messagesDir,
+    };
+  }
+
+  if (messageFiles.length === 0) {
+    return {
+      ok: false,
+      error: "Session exists but message directory is empty",
+      path: messagesDir,
+    };
+  }
+
+  // 5. Parse messages, filter to user/assistant, extract previews
+  interface MessageData {
+    role?: string;
+    content?: unknown;
+  }
+  const allMessages: MessageData[] = [];
+  for (const file of messageFiles) {
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- sequential read needed: message files must be read in order
+      const data = (await Bun.file(join(messagesDir, file)).json()) as Record<
+        string,
+        unknown
+      >;
+      allMessages.push({
+        role: typeof data.role === "string" ? data.role : undefined,
+        content: data.content,
+      });
+    } catch {
+      logDebug(`Skipping message file ${file}: parse error`);
+    }
+  }
+
+  const relevant: OpencodeSessionSummary["transcript"] = [];
+  for (const msg of allMessages) {
+    if (!RELEVANT_ROLES.has(msg.role ?? "")) continue;
+    // Normalize to TranscriptEntry shape for getContentPreview
+    const normalized: TranscriptEntry = { message: { content: msg.content } };
+    relevant.push({
+      role: msg.role!,
+      contentPreview: getContentPreview(normalized),
+    });
+  }
+
+  const trimmed = relevant.length > limit ? relevant.slice(-limit) : relevant;
+  return {
+    ok: true,
+    data: {
+      sessionId: target.id,
+      totalEntries: allMessages.length,
+      relevantEntries: relevant.length,
+      transcript: trimmed,
+    },
+  };
+}
diff --git a/src/helpers/session-context.ts b/src/helpers/session-context.ts
index 7d7c48bb..3eff3b1d 100644
--- a/src/helpers/session-context.ts
+++ b/src/helpers/session-context.ts
@@ -46,9 +46,9 @@ export async function encodeProjectPath(
 }
 
 const RELEVANT_TYPES = new Set(["user", "assistant"]);
-const RELEVANT_ROLES = new Set(["user", "assistant"]);
+export const RELEVANT_ROLES = new Set(["user", "assistant"]);
 
-interface TranscriptEntry {
+export interface TranscriptEntry {
   type?: string;
   role?: string;
   message?: { role?: string; content?: unknown };
@@ -79,7 +79,7 @@ type CursorSessionResult =
   | { ok: false; error: string; path?: string; available?: string[] };
 
 /** Extract a concise content preview from a transcript entry. */
-function getContentPreview(entry: TranscriptEntry): string {
+export function getContentPreview(entry: TranscriptEntry): string {
   const content = entry.message?.content;
   if (typeof content === "string") {
     return content.length > 500 ? content.slice(0, 500) + "..." : content;
diff --git a/tests/commands/session-context.test.ts b/tests/commands/session-context.test.ts
index 304e586e..95cd683e 100644
--- a/tests/commands/session-context.test.ts
+++ b/tests/commands/session-context.test.ts
@@ -29,6 +29,16 @@ describe("registerSessionContextCommand", () => {
     expect(sub).toBeDefined();
   });
 
+  test("registers 'copilot' subcommand", () => {
+    const program = new Command();
+    registerSessionContextCommand(program);
+    const parent = program.commands.find(
+      (c) => c.name() === "session-context"
+    )!;
+    const sub = parent.commands.find((c) => c.name() === "copilot");
+    expect(sub).toBeDefined();
+  });
+
   test("registers 'cursor' subcommand", () => {
     const program = new Command();
     registerSessionContextCommand(program);
@@ -39,6 +49,16 @@ describe("registerSessionContextCommand", () => {
     expect(sub).toBeDefined();
   });
 
+  test("registers 'opencode' subcommand", () => {
+    const program = new Command();
+    registerSessionContextCommand(program);
+    const parent = program.commands.find(
+      (c) => c.name() === "session-context"
+    )!;
+    const sub = parent.commands.find((c) => c.name() === "opencode");
+    expect(sub).toBeDefined();
+  });
+
   test("claude-code subcommand has --max-entries option", () => {
     const program = new Command();
     registerSessionContextCommand(program);
@@ -61,4 +81,28 @@ describe("registerSessionContextCommand", () => {
     expect(opts).toContain("--max-entries");
     expect(opts).toContain("--session-id");
   });
+
+  test("copilot subcommand has --max-entries and --session-id options", () => {
+    const program = new Command();
+    registerSessionContextCommand(program);
+    const parent = program.commands.find(
+      (c) => c.name() === "session-context"
+    )!;
+    const sub = parent.commands.find((c) => c.name() === "copilot")!;
+    const opts = sub.options.map((o) => o.long);
+    expect(opts).toContain("--max-entries");
+    expect(opts).toContain("--session-id");
+  });
+
+  test("opencode subcommand has --max-entries and --session-id options", () => {
+    const program = new Command();
+    registerSessionContextCommand(program);
+    const parent = program.commands.find(
+      (c) => c.name() === "session-context"
+    )!;
+    const sub = parent.commands.find((c) => c.name() === "opencode")!;
+    const opts = sub.options.map((o) => o.long);
+    expect(opts).toContain("--max-entries");
+    expect(opts).toContain("--session-id");
+  });
 });
diff --git a/tests/commands/session-context/copilot.test.ts b/tests/commands/session-context/copilot.test.ts
new file mode 100644
index 00000000..5ba2ad17
--- /dev/null
+++ b/tests/commands/session-context/copilot.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import { Command } from "@commander-js/extra-typings";
+
+import { registerCopilotSessionContextCommand } from "../../../src/commands/session-context/copilot";
+
+describe("registerCopilotSessionContextCommand", () => {
+  test("registers 'copilot' as a subcommand", () => {
+    const parent = new Command("session-context");
+    registerCopilotSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "copilot");
+    expect(sub).toBeDefined();
+  });
+
+  test("has a description", () => {
+    const parent = new Command("session-context");
+    registerCopilotSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "copilot")!;
+    expect(sub.description()).toBeTruthy();
+  });
+
+  test("accepts --max-entries option", () => {
+    const parent = new Command("session-context");
+    registerCopilotSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "copilot")!;
+    const opt = sub.options.find((o) => o.long === "--max-entries");
+    expect(opt).toBeDefined();
+  });
+
+  test("accepts --session-id option", () => {
+    const parent = new Command("session-context");
+    registerCopilotSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "copilot")!;
+    const opt = sub.options.find((o) => o.long === "--session-id");
+    expect(opt).toBeDefined();
+  });
+});
diff --git a/tests/commands/session-context/opencode.test.ts b/tests/commands/session-context/opencode.test.ts
new file mode 100644
index 00000000..da3c1560
--- /dev/null
+++ b/tests/commands/session-context/opencode.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import { Command } from "@commander-js/extra-typings";
+
+import { registerOpencodeSessionContextCommand } from "../../../src/commands/session-context/opencode";
+
+describe("registerOpencodeSessionContextCommand", () => {
+  test("registers 'opencode' as a subcommand", () => {
+    const parent = new Command("session-context");
+    registerOpencodeSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "opencode");
+    expect(sub).toBeDefined();
+  });
+
+  test("has a description", () => {
+    const parent = new Command("session-context");
+    registerOpencodeSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "opencode")!;
+    expect(sub.description()).toBeTruthy();
+  });
+
+  test("accepts --max-entries option", () => {
+    const parent = new Command("session-context");
+    registerOpencodeSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "opencode")!;
+    const opt = sub.options.find((o) => o.long === "--max-entries");
+    expect(opt).toBeDefined();
+  });
+
+  test("accepts --session-id option", () => {
+    const parent = new Command("session-context");
+    registerOpencodeSessionContextCommand(parent);
+    const sub = parent.commands.find((c) => c.name() === "opencode")!;
+    const opt = sub.options.find((o) => o.long === "--session-id");
+    expect(opt).toBeDefined();
+  });
+});
diff --git a/tests/helpers/session-context-copilot.test.ts b/tests/helpers/session-context-copilot.test.ts
new file mode 100644
index 00000000..8fc8f0e8
--- /dev/null
+++ b/tests/helpers/session-context-copilot.test.ts
@@ -0,0 +1,251 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { readCopilotSession } from "../../src/helpers/session-context-copilot";
+
+// This file covers readCopilotSession happy-path and error-case tests.
+
+describe("readCopilotSession", () => {
+  const uniqueId = `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  // Use a fake project root that we'll put in workspace.yaml cwd
+  const projectRoot = resolve(`/__archgate_copilot_test_${uniqueId}`);
+  let stateDir: string;
+
+  beforeEach(() => {
+    stateDir = join(homedir(), ".copilot", "session-state");
+    mkdirSync(stateDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    // Clean up only the session dirs we created (identifiable by uniqueId in events)
+    // We use a tracking array instead
+    for (const dir of createdDirs) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    createdDirs.length = 0;
+  });
+
+  const createdDirs: string[] = [];
+
+  function makeSession(
+    sessionId: string,
+    cwd: string,
+    events?: string[]
+  ): void {
+    const sessionDir = join(stateDir, sessionId);
+    mkdirSync(sessionDir, { recursive: true });
+    createdDirs.push(sessionDir);
+
+    // Write workspace.yaml — use JSON.stringify to escape backslashes
+    // in Windows paths (YAML double-quoted strings use the same escaping)
+    const yaml = `cwd: ${JSON.stringify(cwd)}\nid: ${JSON.stringify(sessionId)}\n`;
+    writeFileSync(join(sessionDir, "workspace.yaml"), yaml);
+
+    // Write events.jsonl if provided
+    if (events) {
+      writeFileSync(join(sessionDir, "events.jsonl"), events.join("\n"));
+    }
+  }
+
+  test("returns data for most recent session matching project", async () => {
+    const sessionId = `copilot-${uniqueId}-1`;
+    makeSession(sessionId, projectRoot, [
+      JSON.stringify({
+        type: "user.message",
+        timestamp: "2026-01-01T00:00:00Z",
+        data: { content: "hello copilot" },
+      }),
+      JSON.stringify({
+        type: "assistant.message",
+        timestamp: "2026-01-01T00:00:01Z",
+        data: { content: "hi there" },
+      }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.sessionId).toBe(sessionId);
+    expect(result.data.sessionFile).toBe("events.jsonl");
+    expect(result.data.totalEntries).toBe(2);
+    expect(result.data.relevantEntries).toBe(2);
+    expect(result.data.transcript[0]).toEqual({
+      role: "user",
+      contentPreview: "hello copilot",
+    });
+    expect(result.data.transcript[1]).toEqual({
+      role: "assistant",
+      contentPreview: "hi there",
+    });
+  });
+
+  test("finds session by sessionId", async () => {
+    const sessionId1 = `copilot-${uniqueId}-first`;
+    const sessionId2 = `copilot-${uniqueId}-second`;
+
+    makeSession(sessionId1, projectRoot, [
+      JSON.stringify({
+        type: "user.message",
+        data: { content: "first session" },
+      }),
+    ]);
+    makeSession(sessionId2, projectRoot, [
+      JSON.stringify({
+        type: "user.message",
+        data: { content: "second session" },
+      }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot, {
+      sessionId: sessionId1,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.sessionId).toBe(sessionId1);
+    expect(result.data.transcript[0]?.contentPreview).toBe("first session");
+  });
+
+  test("returns error when sessionId not found (with available list)", async () => {
+    const sessionId = `copilot-${uniqueId}-real`;
+    makeSession(sessionId, projectRoot, [
+      JSON.stringify({ type: "user.message", data: { content: "real" } }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot, {
+      sessionId: "nonexistent-id",
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("nonexistent-id");
+      expect(result.available).toContain(sessionId);
+    }
+  });
+
+  test("filters to user.message and assistant.message events only", async () => {
+    const sessionId = `copilot-${uniqueId}-filter`;
+    makeSession(sessionId, projectRoot, [
+      JSON.stringify({
+        type: "session.start",
+        data: { context: { repository: "test" } },
+      }),
+      JSON.stringify({
+        type: "tool.call",
+        data: { name: "bash", input: "ls" },
+      }),
+      JSON.stringify({ type: "user.message", data: { content: "visible" } }),
+      JSON.stringify({
+        type: "assistant.message",
+        data: { content: "also visible" },
+      }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.totalEntries).toBe(4);
+    expect(result.data.relevantEntries).toBe(2);
+    expect(result.data.transcript[0]?.contentPreview).toBe("visible");
+    expect(result.data.transcript[1]?.contentPreview).toBe("also visible");
+  });
+
+  test("returns error when session has no events.jsonl", async () => {
+    const sessionId = `copilot-${uniqueId}-noevents`;
+    makeSession(sessionId, projectRoot); // no events array
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("no conversation transcript");
+    }
+  });
+
+  test("returns error when no sessions match the project", async () => {
+    const sessionId = `copilot-${uniqueId}-other`;
+    makeSession(sessionId, "/some/other/project", [
+      JSON.stringify({
+        type: "user.message",
+        data: { content: "wrong project" },
+      }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("No Copilot CLI sessions found");
+    }
+  });
+
+  test("handles malformed events.jsonl", async () => {
+    const sessionId = `copilot-${uniqueId}-bad`;
+    const sessionDir = join(stateDir, sessionId);
+    mkdirSync(sessionDir, { recursive: true });
+    createdDirs.push(sessionDir);
+    writeFileSync(
+      join(sessionDir, "workspace.yaml"),
+      `cwd: ${JSON.stringify(projectRoot)}\nid: ${JSON.stringify(sessionId)}\n`
+    );
+    writeFileSync(join(sessionDir, "events.jsonl"), "}{not valid json at all");
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("no conversation transcript");
+    }
+  });
+
+  test("respects maxEntries — keeps last N relevant entries", async () => {
+    const sessionId = `copilot-${uniqueId}-limit`;
+    const events: string[] = [];
+    for (let i = 0; i < 8; i++) {
+      events.push(
+        JSON.stringify({
+          type: i % 2 === 0 ? "user.message" : "assistant.message",
+          data: { content: `msg ${i}` },
+        })
+      );
+    }
+    makeSession(sessionId, projectRoot, events);
+
+    const result = await readCopilotSession(projectRoot, { maxEntries: 2 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.relevantEntries).toBe(8);
+    expect(result.data.transcript).toHaveLength(2);
+    // slice(-2) keeps last 2 — messages 6 and 7
+    expect(result.data.transcript[0]?.contentPreview).toBe("msg 6");
+    expect(result.data.transcript[1]?.contentPreview).toBe("msg 7");
+  });
+
+  test("returns error when session-state directory does not exist", async () => {
+    const result = await readCopilotSession(
+      "/nonexistent/path/that/wont/match"
+    );
+    // This may return "no sessions found for this project" or "no session-state dir"
+    // depending on whether ~/.copilot/session-state/ exists
+    expect(result.ok).toBe(false);
+  });
+
+  test("truncates string content preview to 500 chars", async () => {
+    const sessionId = `copilot-${uniqueId}-truncate`;
+    makeSession(sessionId, projectRoot, [
+      JSON.stringify({
+        type: "user.message",
+        data: { content: "x".repeat(600) },
+      }),
+    ]);
+
+    const result = await readCopilotSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    const preview = result.data.transcript[0]?.contentPreview ?? "";
+    expect(preview).toHaveLength(503); // 500 chars + "..."
+    expect(preview.endsWith("...")).toBe(true);
+  });
+});
diff --git a/tests/helpers/session-context-opencode.test.ts b/tests/helpers/session-context-opencode.test.ts
new file mode 100644
index 00000000..13a4e517
--- /dev/null
+++ b/tests/helpers/session-context-opencode.test.ts
@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { readOpencodeSession } from "../../src/helpers/session-context-opencode";
+
+// This file covers readOpencodeSession happy-path and error-case tests.
+
+describe("readOpencodeSession", () => {
+  const uniqueId = `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const projectRoot = resolve(`/__archgate_opencode_test_${uniqueId}`);
+  // Use a temp storage dir under homedir to avoid polluting real opencode data
+  const projectHash = `proj_${uniqueId}`;
+  let storageDir: string;
+  let sessionBaseDir: string;
+  let messageBaseDir: string;
+
+  beforeEach(() => {
+    storageDir = join(homedir(), ".local", "share", "opencode", "storage");
+    sessionBaseDir = join(storageDir, "session");
+    messageBaseDir = join(storageDir, "message");
+    mkdirSync(sessionBaseDir, { recursive: true });
+    mkdirSync(messageBaseDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    for (const dir of createdDirs) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    createdDirs.length = 0;
+  });
+
+  const createdDirs: string[] = [];
+
+  function makeSession(
+    sessionId: string,
+    sessionPath: string,
+    messages?: Array<{ id: string; role: string; content: string }>
+  ): void {
+    // Create session metadata file
+    const sessionDir = join(sessionBaseDir, projectHash);
+    mkdirSync(sessionDir, { recursive: true });
+    createdDirs.push(sessionDir);
+
+    const sessionMeta = {
+      id: sessionId,
+      title: `Test session ${sessionId}`,
+      path: sessionPath,
+      updated_at: new Date().toISOString(),
+      created_at: new Date().toISOString(),
+    };
+    writeFileSync(
+      join(sessionDir, `${sessionId}.json`),
+      JSON.stringify(sessionMeta)
+    );
+
+    // Create message files
+    if (messages) {
+      const msgDir = join(messageBaseDir, sessionId);
+      mkdirSync(msgDir, { recursive: true });
+      createdDirs.push(msgDir);
+
+      for (const msg of messages) {
+        const msgData = {
+          id: msg.id,
+          role: msg.role,
+          content: msg.content,
+          session_id: sessionId,
+          created_at: new Date().toISOString(),
+        };
+        writeFileSync(join(msgDir, `${msg.id}.json`), JSON.stringify(msgData));
+      }
+    }
+  }
+
+  test("returns data for most recent session matching project", async () => {
+    const sessionId = `ses_${uniqueId}_1`;
+    makeSession(sessionId, projectRoot, [
+      { id: "msg_001", role: "user", content: "hello opencode" },
+      { id: "msg_002", role: "assistant", content: "hi there" },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.sessionId).toBe(sessionId);
+    expect(result.data.totalEntries).toBe(2);
+    expect(result.data.relevantEntries).toBe(2);
+    expect(result.data.transcript[0]).toEqual({
+      role: "user",
+      contentPreview: "hello opencode",
+    });
+    expect(result.data.transcript[1]).toEqual({
+      role: "assistant",
+      contentPreview: "hi there",
+    });
+  });
+
+  test("finds session by sessionId", async () => {
+    const sessionId1 = `ses_${uniqueId}_first`;
+    const sessionId2 = `ses_${uniqueId}_second`;
+
+    makeSession(sessionId1, projectRoot, [
+      { id: "msg_001", role: "user", content: "first session" },
+    ]);
+    makeSession(sessionId2, projectRoot, [
+      { id: "msg_001", role: "user", content: "second session" },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot, {
+      sessionId: sessionId1,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.sessionId).toBe(sessionId1);
+    expect(result.data.transcript[0]?.contentPreview).toBe("first session");
+  });
+
+  test("returns error when sessionId not found (with available list)", async () => {
+    const sessionId = `ses_${uniqueId}_real`;
+    makeSession(sessionId, projectRoot, [
+      { id: "msg_001", role: "user", content: "real" },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot, {
+      sessionId: "nonexistent-id",
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("nonexistent-id");
+      expect(result.available).toContain(sessionId);
+    }
+  });
+
+  test("filters to user/assistant roles only", async () => {
+    const sessionId = `ses_${uniqueId}_roles`;
+    makeSession(sessionId, projectRoot, [
+      { id: "msg_001", role: "system", content: "system msg" },
+      { id: "msg_002", role: "tool", content: "tool output" },
+      { id: "msg_003", role: "user", content: "visible" },
+      { id: "msg_004", role: "assistant", content: "also visible" },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.totalEntries).toBe(4);
+    expect(result.data.relevantEntries).toBe(2);
+    expect(result.data.transcript[0]?.contentPreview).toBe("visible");
+    expect(result.data.transcript[1]?.contentPreview).toBe("also visible");
+  });
+
+  test("returns error when no sessions match the project", async () => {
+    const sessionId = `ses_${uniqueId}_other`;
+    makeSession(sessionId, "/some/other/project", [
+      { id: "msg_001", role: "user", content: "wrong project" },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain(
+        "No opencode sessions found for this project"
+      );
+    }
+  });
+
+  test("returns error when session has no message directory", async () => {
+    const sessionId = `ses_${uniqueId}_nomsg`;
+    // Create session metadata but no message directory
+    const sessionDir = join(sessionBaseDir, projectHash);
+    mkdirSync(sessionDir, { recursive: true });
+    createdDirs.push(sessionDir);
+
+    const sessionMeta = {
+      id: sessionId,
+      path: projectRoot,
+      updated_at: new Date().toISOString(),
+    };
+    writeFileSync(
+      join(sessionDir, `${sessionId}.json`),
+      JSON.stringify(sessionMeta)
+    );
+
+    const result = await readOpencodeSession(projectRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("no messages");
+    }
+  });
+
+  test("respects maxEntries — keeps last N relevant entries", async () => {
+    const sessionId = `ses_${uniqueId}_limit`;
+    const messages: Array<{ id: string; role: string; content: string }> = [];
+    for (let i = 0; i < 8; i++) {
+      messages.push({
+        id: `msg_${String(i).padStart(3, "0")}`,
+        role: i % 2 === 0 ? "user" : "assistant",
+        content: `msg ${i}`,
+      });
+    }
+    makeSession(sessionId, projectRoot, messages);
+
+    const result = await readOpencodeSession(projectRoot, { maxEntries: 2 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    expect(result.data.relevantEntries).toBe(8);
+    expect(result.data.transcript).toHaveLength(2);
+    // slice(-2) keeps last 2 — messages 6 and 7
+    expect(result.data.transcript[0]?.contentPreview).toBe("msg 6");
+    expect(result.data.transcript[1]?.contentPreview).toBe("msg 7");
+  });
+
+  test("truncates string content preview to 500 chars", async () => {
+    const sessionId = `ses_${uniqueId}_truncate`;
+    makeSession(sessionId, projectRoot, [
+      { id: "msg_001", role: "user", content: "x".repeat(600) },
+    ]);
+
+    const result = await readOpencodeSession(projectRoot);
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+
+    const preview = result.data.transcript[0]?.contentPreview ?? "";
+    expect(preview).toHaveLength(503); // 500 chars + "..."
+    expect(preview.endsWith("...")).toBe(true);
+  });
+
+  test("returns error when storage directory does not exist", async () => {
+    // readOpencodeSession should handle missing storage gracefully
+    const result = await readOpencodeSession(
+      "/nonexistent/path/that/wont/match"
+    );
+    expect(result.ok).toBe(false);
+  });
+});

From 61503cf9e020b507b0eb68895808a8dbc6020318 Mon Sep 17 00:00:00 2001
From: rhuanbarreto <283004+rhuanbarreto@users.noreply.github.com>
Date: Tue, 5 May 2026 20:00:25 +0000
Subject: [PATCH 2/2] docs: regenerate llms-full.txt

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 docs/public/llms-full.txt | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index f4b0112e..2958048b 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -3860,6 +3860,19 @@ archgate session-context claude-code [options]
 | ------------------- | ---------------------------------------- |
 | `--max-entries <n>` | Maximum entries to return (default: 200) |
 
+### archgate session-context copilot
+
+Read the Copilot CLI session transcript for the project. Sessions are matched by their workspace `cwd` field.
+
+```bash
+archgate session-context copilot [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+| `--session-id <id>` | Specific session UUID to read            |
+
 ### archgate session-context cursor
 
 Read the Cursor agent session transcript for the project.
@@ -3873,6 +3886,19 @@ archgate session-context cursor [options]
 | `--max-entries <n>` | Maximum entries to return (default: 200) |
 | `--session-id <id>` | Specific session UUID to read            |
 
+### archgate session-context opencode
+
+Read the opencode session transcript for the project. Sessions are matched by the project `path` field in session metadata.
+
+```bash
+archgate session-context opencode [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+| `--session-id <id>` | Specific session ID to read              |
+
 ## Examples
 
 Read the latest Claude Code session:
@@ -3887,6 +3913,18 @@ Read a specific Cursor session:
 archgate session-context cursor --session-id abc123
 ```
 
+Read the latest Copilot CLI session:
+
+```bash
+archgate session-context copilot
+```
+
+Read the latest opencode session:
+
+```bash
+archgate session-context opencode
+```
+
 ---
 
 ## Reference: archgate telemetry