@bramblex/codex-workbench 0.1.14 → 0.1.15

package/README.md

@@ -1,6 +1,6 @@
 # codex-workbench
 
-> A keyboard-driven terminal UI for browsing, organizing, and resuming [Codex](https://github.com/openai/codex) sessions — locally and across SSH remotes.
+> A keyboard-driven terminal UI for browsing, organizing, and resuming coding-agent sessions — locally and across SSH remotes.
 
 [![npm version](https://img.shields.io/npm/v/@bramblex/codex-workbench)](https://www.npmjs.com/package/@bramblex/codex-workbench)
 [![license](https://img.shields.io/npm/l/@bramblex/codex-workbench)](LICENSE)
@@ -14,9 +14,11 @@
 
 ## What is it?
 
-codex-workbench is an **interactive terminal UI** for your Codex sessions. Instead of digging through `~/.codex/sessions/` by hand, you get a fast, keyboard-driven interface to **browse, search, rename, annotate, fork, archive, and delete** sessions — all without leaving the terminal.
+codex-workbench is an **interactive terminal UI** for coding-agent sessions. Instead of digging through backend-specific session directories by hand, you get a fast, keyboard-driven interface to **browse, search, rename, annotate, fork, archive, and delete** sessions — all without leaving the terminal.
 
-It also connects to **remote machines over SSH**, so you can manage Codex sessions across all your servers from a single pane of glass.
+It also connects to **remote machines over SSH**, so you can manage sessions across all your servers from a single pane of glass.
+
+Built-in backends currently include [Codex](https://github.com/openai/codex) and pi. The backend layer is intentionally provider-based so additional agents can be added without changing the TUI workflow.
 
 A handful of CLI subcommands are available for scripting, but the TUI is the product.
 
@@ -28,7 +30,7 @@ A handful of CLI subcommands are available for scripting, but the TUI is the pro
 npm install -g @bramblex/codex-workbench
 ```
 
-Verify Codex is reachable, then open the workbench:
+Verify your backends are reachable, then open the workbench:
 
 ```bash
 codex-workbench doctor
@@ -43,13 +45,13 @@ That's it. `cwb` with no arguments opens the TUI.
 
 The TUI has three panes: **sources & projects** on the left, **sessions** on the upper right, and **session details** below. Local sessions load instantly; remote SSH sources stream in asynchronously.
 
-When you resume or start a session, Codex takes over the terminal. When it exits, the workbench redraws.
+When you resume or start a session, the selected backend takes over the terminal. When it exits, the workbench redraws.
 
 ### Keyboard shortcuts
 
 | Key | Action |
 |-----|--------|
-| `Enter` | Resume selected session in Codex |
+| `Enter` | Resume selected session in its backend |
 | `Tab` / `S-Tab` | Switch focus between panes |
 | `←` `→` / `h` `l` | Move between sources, sessions, and details |
 | `↑` `↓` / `j` `k` | Move selection up/down |
@@ -92,7 +94,7 @@ ssh user@host 'cwb list --json'
 
 ### Configuration
 
-Create `~/.codex/codex-workbench.config.json`:
+Create `~/.cwb/config.json`:
 
 ```json
 {
@@ -121,7 +123,22 @@ Create `~/.codex/codex-workbench.config.json`:
 | `command` | No | Path to `cwb` on the remote (default: `cwb`) |
 | `sshArgs` | No | Extra SSH flags, e.g. `["-p", "2222"]` |
 
-Operations like rename, note, hide, new, resume, fork, archive, and delete are forwarded to the remote `cwb` transparently.
+Operations like rename, note, new, resume, fork, archive, and delete are forwarded to the remote `cwb` transparently.
+
+Remote backends are supported as long as the remote `cwb` can read them.
+
+---
+
+## Backends
+
+codex-workbench auto-detects installed backends by checking their session directories.
+
+| Backend | Sessions | Binary override | Notes |
+|---------|----------|-----------------|-------|
+| `codex` | `$CODEX_SESSIONS_DIR` or `~/.codex/sessions` | `CODEX_BIN` | Uses the Codex CLI for new, resume, fork, archive, unarchive, and delete. |
+| `pi` | `$PI_CODING_AGENT_SESSION_DIR` or `$PI_CODING_AGENT_DIR/sessions` | `PI_BIN` | Uses the pi CLI for new, resume, and fork. Archive/unarchive use workbench metadata; delete removes the session file. |
+
+Session metadata such as custom names, notes, and archive state is stored in workbench's own metadata file, not inside backend session files.
 
 ---
 
@@ -133,31 +150,31 @@ The TUI is the primary interface, but every action is also available as a CLI su
 cwb list                           # human-readable, grouped by source + project
 cwb list --json --compact          # machine-readable, omits message history
 cwb list --cwd ~/projects/foo      # filter to one working directory
-cwb list --all                     # include archived and hidden sessions
+cwb list --all                     # include archived sessions
+cwb backends --json                # list detected local backends
 
 cwb show <session>                 # full session details
 cwb rename <session> "fix auth"    # give a session a memorable name
 cwb note <session> "clock skew"    # attach a persistent note
 cwb archive <session>              # archive without deleting
 cwb unarchive <session>
-cwb hide <session>                 # remove from default list, keep on disk
-cwb unhide <session>
 cwb fork <session>
 cwb delete <session> --force
 
-cwb new --cwd ~/projects/foo "Summarize this repo"
+cwb new --cwd ~/projects/foo --backend codex "Summarize this repo"
+cwb new --cwd ~/projects/foo --backend pi "Summarize this repo"
 cwb resume <session> "what was the conclusion about the rate limiter?"
 
 cwb dirs --cwd ~/projects
 cwb mkdir ~/projects my-new-feature
 
-cwb doctor                         # check Codex binary discovery
+cwb doctor                         # check available backends and binaries
 cwb delete <session> --file        # force-delete broken session file
 ```
 
 `<session>` can be a full session id, a unique prefix, a saved custom name, or a session filename.
 
-When you run `new` or `resume`, Codex takes over the terminal. When it exits, codex-workbench returns.
+When you run `new` or `resume`, the selected backend takes over the terminal. When it exits, codex-workbench returns. In the TUI, `n` scans the current source for available backends; local sources are scanned directly and remote sources are scanned with `cwb backends --json` over SSH.
 
 ---
 
@@ -165,14 +182,24 @@ When you run `new` or `resume`, Codex takes over the terminal. When it exits, co
 
 | Variable | Default | Description |
 |----------|---------|-------------|
+| `CWB_HOME` | `~/.cwb` | codex-workbench data directory |
+| `CWB_META` | `$CWB_HOME/metadata.json` | Workbench metadata (names, notes, archive state) |
+| `CWB_CONFIG` | `$CWB_HOME/config.json` | SSH remote sources config |
 | `CODEX_HOME` | `~/.codex` | Codex data directory |
 | `CODEX_SESSIONS_DIR` | `$CODEX_HOME/sessions` | Session JSONL files |
-| `CODEX_WORKBENCH_META` | `$CODEX_HOME/codex-workbench.json` | Workbench metadata (names, notes) |
-| `CODEX_WORKBENCH_CONFIG` | `$CODEX_HOME/codex-workbench.config.json` | SSH remote sources config |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi coding agent data directory |
+| `PI_CODING_AGENT_SESSION_DIR` | `$PI_CODING_AGENT_DIR/sessions` | pi session JSONL files |
+| `CODEX_WORKBENCH_META` | unset | Legacy override for `CWB_META` |
+| `CODEX_WORKBENCH_CONFIG` | unset | Legacy override for `CWB_CONFIG` |
 | `CODEX_BIN` | auto-detected | Force a specific Codex executable |
+| `PI_BIN` | auto-detected | Force a specific pi executable |
 
 By default, codex-workbench discovers the `codex` binary through your login shell's `PATH`. Set `CODEX_BIN` to override.
 
+`cwb doctor` reports every backend it can see.
+
+On first run, workbench moves legacy config files from `~/.codex/` into `~/.cwb/` if the new files do not exist yet.
+
 ---
 
 ## Troubleshooting
@@ -185,10 +212,18 @@ Run `codex-workbench doctor` to see where codex-workbench is looking. Common fix
 - Set `CODEX_BIN=/path/to/codex` to point directly at the executable
 - Make sure your shell profile (`~/.zshrc`, `~/.bashrc`) adds Codex to `PATH`
 
-### No sessions appear
+### No Codex sessions appear
 
 Make sure you've run Codex at least once. Sessions are stored as `.jsonl` files under `$CODEX_SESSIONS_DIR`. Run `ls ~/.codex/sessions/` to verify.
 
+### No pi sessions appear
+
+Make sure you've run the pi coding agent at least once. Sessions are stored as `.jsonl` files under `$PI_CODING_AGENT_SESSION_DIR` or `$PI_CODING_AGENT_DIR/sessions`. Run `ls ~/.pi/agent/sessions/` to verify.
+
+### A backend is missing from doctor
+
+Backends appear only when their session directory exists. For a new backend integration, add a provider under `src/providers/` with session discovery, parsing, binary discovery, and command routing.
+
 ### Remote source shows an error
 
 Verify the remote is reachable and has `cwb` in its non-interactive PATH:
@@ -237,15 +272,20 @@ bin/codex-workbench          # executable entry point
 src/
   cli.js                     # CLI argument parsing and command dispatch
   cli-output.js              # terminal output formatters
-  codex-bin.js               # Codex binary discovery (PATH, shell, fallback)
+  codex-bin.js               # legacy Codex binary discovery wrapper
   config.js                  # environment-derived path constants
   model/
-    session-store.js         # session JSONL parsing and metadata persistence
+    metadata.js              # workbench-owned metadata persistence
+    session-store.js         # provider session aggregation and metadata merge
     format.js                # id/time/text formatting helpers
     directories.js           # filesystem directory listing and creation
     workbench-config.js      # SSH remote source config loader
+  providers/
+    codex.js                 # Codex provider
+    pi.js                    # pi provider
+    index.js                 # provider registry
   services/
-    codex-runner.js          # spawn Codex processes (new, resume, fork, etc.)
+    codex-runner.js          # backward-compatible provider runner wrapper
     session-sources.js       # aggregates local + remote session lists
     ssh-runner.js            # runs cwb commands over SSH (sync + async)
   ui/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bramblex/codex-workbench",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Terminal workbench for browsing and managing local and SSH Codex sessions.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node -e \"const fs=require('fs'),{spawnSync}=require('child_process');function files(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>e.isDirectory()?files(d+'/'+e.name):e.name.endsWith('.js')?[d+'/'+e.name]:[])}for(const f of files('src')){const r=spawnSync(process.execPath,['--check',f],{stdio:'inherit'});if(r.status)process.exit(r.status)}\" && node --check bin/codex-workbench && node --check scripts/pty-codex.js && node --check scripts/tui-pty-codex.js && node --check scripts/blessed-xterm-codex.js && node test/codex-bin.test.js && node test/blessed-compat.test.js && node test/session-sources.test.js && node test/smoke.js",
+    "test": "node -e \"const fs=require('fs'),{spawnSync}=require('child_process');function files(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>e.isDirectory()?files(d+'/'+e.name):e.name.endsWith('.js')?[d+'/'+e.name]:[])}for(const f of files('src')){const r=spawnSync(process.execPath,['--check',f],{stdio:'inherit'});if(r.status)process.exit(r.status)}\" && node --check bin/codex-workbench && node --check scripts/pty-codex.js && node --check scripts/tui-pty-codex.js && node --check scripts/blessed-xterm-codex.js && node test/codex-bin.test.js && node test/blessed-compat.test.js && node test/config-paths.test.js && node test/session-sources.test.js && node test/workbench-config.test.js && node test/smoke.js",
     "pty:codex": "node scripts/pty-codex.js",
     "tui:codex": "node scripts/tui-pty-codex.js",
     "xterm:codex": "node scripts/blessed-xterm-codex.js"

package/src/cli-output.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const path = require('path');
-const { inspectCodexBin } = require('./codex-bin');
+const codex = require('./providers/codex');
+const { getAvailableProviders } = require('./providers');
 const { localTime, shortId, truncate } = require('./model/format');
 
 function usage() {
@@ -10,33 +11,35 @@ function usage() {
 Usage:
   codex-workbench [ui]
   codex-workbench doctor
+  codex-workbench backends [--json]
   codex-workbench list [--json] [--compact] [--cwd <dir>] [--all]
   codex-workbench show <session>
   codex-workbench rename <session> <name>
   codex-workbench note <session> <note>
-  codex-workbench new [--cwd <dir>] [prompt...]
+  codex-workbench new [--cwd <dir>] [--backend <backend>] [prompt...]
   codex-workbench dirs [--cwd <dir>] [--json]
   codex-workbench mkdir [--cwd <dir>] <name> [--json]
   codex-workbench resume <session> [prompt...]
   codex-workbench fork <session>
   codex-workbench archive <session>
   codex-workbench unarchive <session>
-  codex-workbench hide <session>
-  codex-workbench unhide <session>
   codex-workbench delete <session> [--force] [--file]
 
 Environment:
+  CWB_HOME              default: ~/.cwb
+  CWB_META              default: $CWB_HOME/metadata.json
+  CWB_CONFIG            default: $CWB_HOME/config.json
   CODEX_HOME            default: ~/.codex
   CODEX_SESSIONS_DIR    default: $CODEX_HOME/sessions
-  CODEX_WORKBENCH_META  default: $CODEX_HOME/codex-workbench.json
-  CODEX_WORKBENCH_CONFIG default: $CODEX_HOME/codex-workbench.config.json
+  CODEX_WORKBENCH_META  legacy override for CWB_META
+  CODEX_WORKBENCH_CONFIG legacy override for CWB_CONFIG
   CODEX_BIN             default: codex from shell PATH
 `);
 }
 
 function printList(sessions, opts = {}) {
   const filtered = sessions.filter((session) => {
-    if (!opts.all && (session.archived || session.hidden)) return false;
+    if (!opts.all && session.archived) return false;
     if (opts.cwd) return path.resolve(session.cwd) === path.resolve(opts.cwd);
     return true;
   });
@@ -55,8 +58,8 @@ function printList(sessions, opts = {}) {
   for (const group of groups.values()) {
     console.log(`\n${group.source ? `${group.source}: ` : ''}${group.cwd}`);
     for (const session of group.sessions) {
-      const label = session.name || truncate(session.first || session.last || '(no prompt)', 56);
-      const flags = [session.archived ? 'archived' : '', session.hidden ? 'hidden' : '', session.note ? 'note' : ''].filter(Boolean).join(',');
+      const label = session.name || truncate(session.first || session.last || '(no prompt)', 52);
+      const flags = [session.backend || '', session.archived ? 'archived' : '', session.note ? 'note' : ''].filter(Boolean).join(',');
       console.log(`  ${shortId(session.id)}  ${localTime(session.updatedAt)}  ${String(session.turns).padStart(2)} turns  ${flags ? `[${flags}] ` : ''}${label}`);
     }
   }
@@ -69,8 +72,9 @@ function compactSession(session) {
 }
 
 function printShow(session) {
-  console.log(`${session.name || '(unnamed)'} ${session.archived ? '[archived]' : ''}${session.hidden ? '[hidden]' : ''}`);
+  console.log(`${session.name || '(unnamed)'} ${session.archived ? '[archived]' : ''}`);
   console.log(`id:       ${session.id}`);
+  console.log(`backend:  ${session.backend || 'unknown'}`);
   if (session.sourceLabel) console.log(`source:   ${session.sourceLabel}`);
   console.log(`cwd:      ${session.cwd}`);
   console.log(`started:  ${localTime(session.startedAt)}`);
@@ -87,24 +91,32 @@ function printShow(session) {
 }
 
 function printDoctor() {
-  const result = inspectCodexBin();
+  const providers = getAvailableProviders();
+
   console.log('codex-workbench doctor');
-  console.log(`status: ${result.ok ? 'ok' : 'error'}`);
-  if (result.path) console.log(`codex:  ${result.path}`);
-  if (result.source) console.log(`source: ${result.source}`);
-  if (result.error) console.log(`error:  ${result.error}`);
-  console.log('\nChecks:');
-  for (const check of result.checks) {
-    const parts = [
-      check.source,
-      check.mode ? `mode=${check.mode}` : '',
-      check.shell ? `shell=${check.shell}` : '',
-      check.path ? `path=${check.path}` : '',
-      `executable=${check.executable ? 'yes' : 'no'}`,
-    ].filter(Boolean);
-    console.log(`  - ${parts.join(' ')}`);
+  console.log(`\nBackends detected: ${providers.length ? providers.map((p) => p.label).join(', ') : 'none'}`);
+
+  for (const provider of providers) {
+    console.log(`\n-- ${provider.label} --`);
+    const bin = provider.resolveBin();
+    if (bin) {
+      console.log(`  binary:   ${bin}`);
+    } else {
+      console.log(`  binary:   not found`);
+      try { provider.resolveBin(); } catch (err) { console.log(`  error:    ${err.message}`); }
+    }
+    try {
+      const files = provider.getSessionFiles();
+      console.log(`  sessions: ${files.length} file${files.length === 1 ? '' : 's'}`);
+    } catch (err) {
+      console.log(`  sessions: error - ${err.message}`);
+    }
+  }
+
+  if (!providers.length) {
+    console.log('\nNo backends available. Install Codex CLI or pi coding agent.');
+    process.exitCode = 1;
   }
-  if (!result.ok) process.exitCode = 1;
 }
 
 module.exports = {

package/src/cli.js

@@ -18,6 +18,9 @@ const {
   runNewCodexSession,
   usableCwd,
 } = require('./services/codex-runner');
+const { defaultBackend } = require('./services/session-sources');
+const { listLocalBackends } = require('./services/session-sources');
+const { getProvider } = require('./providers');
 const { runWorkbench } = require('./ui/workbench');
 const { createChildDirectory, listDirectories } = require('./model/directories');
 
@@ -34,6 +37,10 @@ function parseFlags(args) {
       if (i + 1 >= args.length) throw new Error('--cwd requires a directory.');
       out.cwd = args[++i];
     }
+    else if (arg === '--backend') {
+      if (i + 1 >= args.length) throw new Error('--backend requires a backend id.');
+      out.backend = args[++i];
+    }
     else out._.push(arg);
   }
   return out;
@@ -45,6 +52,12 @@ async function main() {
 
   const flags = parseFlags(rest);
   if (cmd === 'doctor') return printDoctor();
+  if (cmd === 'backends') {
+    const backends = listLocalBackends();
+    if (flags.json) console.log(JSON.stringify(backends, null, 2));
+    else backends.forEach((backend) => console.log(`${backend.id}\t${backend.label}`));
+    return undefined;
+  }
   if (cmd === 'dirs') {
     const payload = listDirectories(flags.cwd || process.cwd(), usableCwd);
     if (flags.json) console.log(JSON.stringify(payload, null, 2));
@@ -68,13 +81,15 @@ async function main() {
   if (cmd === 'show') return printShow(resolveSession(flags._[0], sessions));
   if (cmd === 'rename') return updateMetadata(resolveSession(flags._[0], sessions), { name: flags._.slice(1).join(' ') });
   if (cmd === 'note') return updateMetadata(resolveSession(flags._[0], sessions), { note: flags._.slice(1).join(' ') });
-  if (cmd === 'new' || cmd === 'start') return runNewCodexSession(flags.cwd || process.cwd(), flags._, true);
+  if (cmd === 'new' || cmd === 'start') {
+    const backend = flags.backend || defaultBackend();
+    getProvider(backend);
+    return runNewCodexSession(flags.cwd || process.cwd(), flags._, true, backend);
+  }
   if (cmd === 'resume') return runCodexCommand('resume', resolveSession(flags._[0], sessions), flags._.slice(1), true);
   if (cmd === 'fork') return runCodexCommand('fork', resolveSession(flags._[0], sessions), [], true);
   if (cmd === 'archive') return runCodexCommand('archive', resolveSession(flags._[0], sessions));
   if (cmd === 'unarchive') return runCodexCommand('unarchive', resolveSession(flags._[0], sessions));
-  if (cmd === 'hide') return updateMetadata(resolveSession(flags._[0], sessions), { hidden: true });
-  if (cmd === 'unhide') return updateMetadata(resolveSession(flags._[0], sessions), { hidden: false });
   if (cmd === 'delete') {
     const session = resolveSession(flags._[0], sessions);
     if (flags.file) return deleteSessionFile(session);

package/src/config.js

@@ -1,18 +1,58 @@
 'use strict';
 
+const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
 const HOME = os.homedir();
+
+// Codex paths (backward compatible env vars)
 const CODEX_HOME = process.env.CODEX_HOME || path.join(HOME, '.codex');
-const SESSIONS_DIR = process.env.CODEX_SESSIONS_DIR || path.join(CODEX_HOME, 'sessions');
-const META_PATH = process.env.CODEX_WORKBENCH_META || process.env.CSM_META || path.join(CODEX_HOME, 'codex-workbench.json');
-const CONFIG_PATH = process.env.CODEX_WORKBENCH_CONFIG || path.join(CODEX_HOME, 'codex-workbench.config.json');
+const CODEX_SESSIONS_DIR = process.env.CODEX_SESSIONS_DIR || path.join(CODEX_HOME, 'sessions');
+
+// Workbench-owned paths. Keep separate from provider-owned directories.
+const CWB_HOME = process.env.CWB_HOME || path.join(HOME, '.cwb');
+
+// pi coding agent paths
+const PI_CODING_AGENT_DIR = process.env.PI_CODING_AGENT_DIR || path.join(HOME, '.pi', 'agent');
+const PI_SESSIONS_DIR = process.env.PI_CODING_AGENT_SESSION_DIR || path.join(PI_CODING_AGENT_DIR, 'sessions');
+
+function migrateLegacyFile(legacyPath, nextPath) {
+  if (!legacyPath || !nextPath || legacyPath === nextPath) return;
+  if (fs.existsSync(nextPath) || !fs.existsSync(legacyPath)) return;
+  fs.mkdirSync(path.dirname(nextPath), { recursive: true });
+  fs.renameSync(legacyPath, nextPath);
+}
+
+const LEGACY_META_PATH = path.join(CODEX_HOME, 'codex-workbench.json');
+const LEGACY_CONFIG_PATH = path.join(CODEX_HOME, 'codex-workbench.config.json');
+
+const META_PATH = process.env.CWB_META ||
+  process.env.CODEX_WORKBENCH_META ||
+  process.env.CSM_META ||
+  path.join(CWB_HOME, 'metadata.json');
+
+const CONFIG_PATH = process.env.CWB_CONFIG ||
+  process.env.CODEX_WORKBENCH_CONFIG ||
+  path.join(CWB_HOME, 'config.json');
+
+if (!process.env.CWB_META && !process.env.CODEX_WORKBENCH_META && !process.env.CSM_META) {
+  migrateLegacyFile(LEGACY_META_PATH, META_PATH);
+}
+if (!process.env.CWB_CONFIG && !process.env.CODEX_WORKBENCH_CONFIG) {
+  migrateLegacyFile(LEGACY_CONFIG_PATH, CONFIG_PATH);
+}
 
 module.exports = {
   HOME,
+  CWB_HOME,
   CODEX_HOME,
+  CODEX_SESSIONS_DIR,
+  LEGACY_CONFIG_PATH,
+  LEGACY_META_PATH,
+  PI_CODING_AGENT_DIR,
+  PI_SESSIONS_DIR,
   CONFIG_PATH,
-  SESSIONS_DIR,
+  SESSIONS_DIR: CODEX_SESSIONS_DIR, // backward compat: default sessions dir (legacy)
   META_PATH,
 };

package/src/model/metadata.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { META_PATH } = require('../config');
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function loadMeta() {
+  const data = readJson(META_PATH, { sessions: {} });
+  if (!data.sessions) data.sessions = {};
+  return data;
+}
+
+function updateMetadata(session, patch) {
+  const meta = loadMeta();
+  meta.sessions[session.id] = { ...(meta.sessions[session.id] || {}), ...patch };
+  meta.updatedAt = new Date().toISOString();
+  writeJson(META_PATH, meta);
+}
+
+function removeMetadata(session) {
+  const meta = loadMeta();
+  delete meta.sessions[session.id];
+  meta.updatedAt = new Date().toISOString();
+  writeJson(META_PATH, meta);
+}
+
+module.exports = {
+  loadMeta,
+  removeMetadata,
+  updateMetadata,
+};