@proflandrigan/shards 1.1.0

package/tools/shards-gates.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+// shards-gates — diagnostics CLI for gate state
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const GATE_DIR = path.join(process.cwd(), '.shards', 'gates');
+const AUTO_DIR = path.join(process.cwd(), '.shards', 'auto');
+const STATE_FILE = path.join(GATE_DIR, 'state.json');
+const VIOLATIONS_FILE = path.join(GATE_DIR, 'violations.jsonl');
+const HISTORY_FILE = path.join(GATE_DIR, 'gates.jsonl');
+const AUTO_STATE_FILE = path.join(AUTO_DIR, 'state.json');
+
+// Read state.json and normalize to the v2 shape. Backward-compatible: a legacy
+// single-slot object is upgraded in memory (mirrors tools/gate-hook/state.js).
+function readState() {
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); }
+  catch { return { version: 2, sessions: {}, history: [] }; }
+  if (!raw || typeof raw !== 'object') return { version: 2, sessions: {}, history: [] };
+  if (raw.version === 2 || raw.sessions) {
+    return {
+      version: 2,
+      sessions: (raw.sessions && typeof raw.sessions === 'object') ? raw.sessions : {},
+      history: Array.isArray(raw.history) ? raw.history : [],
+    };
+  }
+  // Legacy single-slot upgrade.
+  const sessions = {};
+  if (raw.open) {
+    sessions[raw.agent || '__legacy__'] = {
+      open: true,
+      id: raw.id,
+      phase: typeof raw.phase !== 'undefined' ? raw.phase : null,
+      kind: raw.kind || null,
+      agent: raw.agent || null,
+      opened_at: raw.opened_at || null,
+    };
+  }
+  return { version: 2, sessions, history: Array.isArray(raw.history) ? raw.history : [] };
+}
+
+// Open session slots as [sessionId, gate] pairs.
+function openSessions(s) {
+  return Object.entries(s.sessions || {}).filter(([, g]) => g && g.open);
+}
+
+function readAutoState() {
+  try { return JSON.parse(fs.readFileSync(AUTO_STATE_FILE, 'utf8')); }
+  catch { return { open: false, history: [] }; }
+}
+
+function readJsonl(file, limit) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    const entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    return limit ? entries.slice(-limit) : entries;
+  } catch { return []; }
+}
+
+// Atomic write helper — mirrors tools/gate-hook/state.js. Used by
+// force-close so an operator override doesn't get clobbered by a concurrent
+// reader / writer.
+function atomicWriteJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+function formatDate(iso) {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleString();
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+function cmdStatus() {
+  const s = readState();
+  const open = openSessions(s);
+  console.log('\n── Gate Status ──────────────────────────────');
+  if (open.length > 0) {
+    console.log(`  Status:    OPEN (${open.length} session${open.length === 1 ? '' : 's'})`);
+    for (const [sessionId, g] of open) {
+      console.log(`  ┌─ session ${sessionId}`);
+      console.log(`  │  Gate ID:   ${g.id}`);
+      console.log(`  │  Phase:     ${g.phase || '?'}`);
+      console.log(`  │  Kind:      ${g.kind || '?'}`);
+      console.log(`  │  Agent:     ${g.agent || '?'}`);
+      console.log(`  │  Opened at: ${formatDate(g.opened_at)}`);
+    }
+  } else {
+    console.log('  Status:    closed (no session has an open gate)');
+  }
+
+  const history = (s.history || []).slice(-10);
+  if (history.length > 0) {
+    console.log('\n── Last 10 Gates ────────────────────────────');
+    for (const h of history) {
+      const kindTag = h.kind && h.kind !== 'phase' ? ` [${h.kind}]` : '';
+      console.log(`  [${h.id}]${kindTag} phase=${h.phase} opened=${formatDate(h.opened_at)} closed=${formatDate(h.closed_at)}`);
+    }
+  }
+  console.log('');
+}
+
+// `checkpoint` and `confirm` are both non-advancing kinds. Advisory-mode
+// checkpoints (SHARDS_CHECKPOINT_ENFORCE=0) are logged only to the JSONL
+// history file — they never enter state.json.history. To give an accurate
+// view we merge both sources, dedup'ing by (gate_id, opened_at|ts).
+const CHECKPOINT_KINDS = new Set(['checkpoint', 'confirm']);
+
+function cmdCheckpoints() {
+  const s = readState();
+  const stateEntries = (s.history || []).filter(h => h.kind && CHECKPOINT_KINDS.has(h.kind));
+  const jsonl = readJsonl(HISTORY_FILE);
+  // Advisory-mode entries: { event: 'advisory', kind, gate_id, phase, ts }.
+  // Opened/closed pairs: { event, gate_id, kind, ts, ... }.
+  // We keep advisories and opened-events as separate rows since advisories
+  // never have a corresponding close.
+  const jsonlEntries = jsonl.filter(e =>
+    e && e.kind && CHECKPOINT_KINDS.has(e.kind) &&
+    (e.event === 'advisory' || e.event === 'opened')
+  );
+
+  // Dedup: state.history entries are confirmed closes; the same gate also
+  // appears in jsonl as an 'opened' event. Drop jsonl 'opened' rows that have
+  // a corresponding closed entry in state.history by gate_id+opened_at.
+  const closedKeys = new Set(
+    stateEntries.map(h => `${h.id}|${h.opened_at || ''}`)
+  );
+
+  const merged = [
+    ...stateEntries.map(h => ({
+      source: 'state',
+      id: h.id,
+      kind: h.kind,
+      phase: h.phase,
+      opened_at: h.opened_at,
+      closed_at: h.closed_at,
+      confirmed_by: h.confirmed_by,
+    })),
+    ...jsonlEntries
+      .filter(e => {
+        if (e.event !== 'opened') return true; // advisory always shown
+        // Skip opened rows whose close is already in state.history.
+        return !closedKeys.has(`${e.gate_id}|${e.ts || ''}`) &&
+               ![...closedKeys].some(k => k.startsWith(`${e.gate_id}|`));
+      })
+      .map(e => ({
+        source: 'jsonl',
+        id: e.gate_id,
+        kind: e.kind,
+        phase: e.phase,
+        opened_at: e.ts,
+        closed_at: null,
+        advisory: e.event === 'advisory',
+      })),
+  ];
+
+  if (merged.length === 0) {
+    console.log('\nNo checkpoint gates recorded in the current session.\n');
+    return;
+  }
+
+  console.log(`\n── Checkpoint / Confirm History (${merged.length} entries) ──────────────`);
+  for (const h of merged) {
+    const tag = h.advisory ? ' [advisory]' : '';
+    const kindLabel = h.kind ? `kind=${h.kind} ` : '';
+    console.log(`  [${h.id}]${tag} ${kindLabel}phase=${h.phase} opened=${formatDate(h.opened_at)} closed=${formatDate(h.closed_at)} via=${h.confirmed_by || '—'}`);
+  }
+  console.log('');
+}
+
+function cmdHistory() {
+  const entries = readJsonl(HISTORY_FILE);
+  if (entries.length === 0) {
+    console.log('\nNo gate history yet.\n');
+    return;
+  }
+  console.log(`\n── Gate History (${entries.length} entries) ──────────────`);
+  for (const e of entries) {
+    console.log(`  [${e.ts}] ${e.event} gate=${e.gate_id}`);
+  }
+  console.log('');
+}
+
+function cmdViolations() {
+  const entries = readJsonl(VIOLATIONS_FILE);
+  if (entries.length === 0) {
+    console.log('\nNo violations recorded.\n');
+    return;
+  }
+  console.log(`\n── Violations (${entries.length} total) ──────────────────`);
+  for (const e of entries) {
+    console.log(`  [${e.ts}] ${e.type} gate=${e.gate_id} reason=${e.reason}`);
+  }
+  console.log('');
+}
+
+function cmdForceClose() {
+  const s = readState();
+  // Operator override unsticks EVERYONE — clear all session slots, appending an
+  // operator-force-close history entry per previously-open session.
+  const open = openSessions(s);
+  const wasOpen = open.length > 0;
+  const closed_at = new Date().toISOString();
+  const newState = {
+    version: 2,
+    sessions: {},
+    history: [
+      ...(s.history || []),
+      ...open.map(([, g]) => ({
+        id: g.id || 'unknown',
+        phase: g.phase,
+        kind: g.kind,
+        opened_at: g.opened_at,
+        closed_at,
+        confirmed_by: 'operator-force-close',
+      })),
+    ],
+  };
+
+  // Also reset auto-verify state. If an auto-verify block was open, its
+  // budget would otherwise remain live after the operator override and the
+  // next bulk-read tool call could be silently auto-approved against the
+  // wishes of the operator who just force-closed the session.
+  const auto = readAutoState();
+  const autoWasOpen = !!auto.open;
+  let autoReset = null;
+  if (autoWasOpen) {
+    autoReset = {
+      open: false,
+      history: [...(auto.history || []), {
+        id: auto.id || 'unknown',
+        agent: auto.agent || null,
+        phase: auto.phase || null,
+        opened_at: auto.opened_at || null,
+        closed_at: new Date().toISOString(),
+        closed_reason: 'operator-force-close',
+        approvals_used: (auto.tool_budget_initial || 0) - (auto.tool_budget_remaining || 0),
+      }],
+    };
+  }
+
+  try {
+    fs.mkdirSync(GATE_DIR, { recursive: true });
+    atomicWriteJson(STATE_FILE, newState);
+    if (autoReset) {
+      atomicWriteJson(AUTO_STATE_FILE, autoReset);
+    }
+    // Log to violations — one entry per previously-open session gate.
+    const ts = new Date().toISOString();
+    const lines = (wasOpen ? open : [[null, { id: 'unknown' }]]).map(([sid, g]) =>
+      JSON.stringify({
+        type: 'operator-force-close',
+        gate_id: g.id || 'unknown',
+        session_id: sid || null,
+        auto_verify_was_open: autoWasOpen,
+        auto_block_id: auto.id || null,
+        reason: 'operator force-close',
+        ts,
+      })
+    );
+    fs.appendFileSync(VIOLATIONS_FILE, lines.join('\n') + '\n');
+
+    if (wasOpen) {
+      const ids = open.map(([, g]) => `'${g.id}'`).join(', ');
+      console.log(`\nForce-closed ${open.length} gate${open.length === 1 ? '' : 's'}: ${ids}.`);
+    } else {
+      console.log('\nGate was already closed.');
+    }
+    if (autoWasOpen) {
+      console.log(`Also reset auto-verify block '${auto.id}' (was open).`);
+    } else {
+      console.log('Auto-verify state was already closed.');
+    }
+    console.log('');
+  } catch (err) {
+    console.error('Error force-closing gate:', err.message);
+  }
+}
+
+// ─── CLI entry ────────────────────────────────────────────────────────────────
+
+const cmd = process.argv[2] || 'status';
+
+switch (cmd) {
+  case 'status':      cmdStatus(); break;
+  case 'history':     cmdHistory(); break;
+  case 'checkpoints': cmdCheckpoints(); break;
+  case 'violations':  cmdViolations(); break;
+  case 'force-close': cmdForceClose(); break;
+  default:
+    console.log(`
+shards-gates — Gate enforcement diagnostics
+
+Usage:
+  shards-gates status          Print current gate state and last 10 history entries
+  shards-gates history         Full gate history dump
+  shards-gates checkpoints     List checkpoint / confirm gates (merges advisory-mode entries from JSONL)
+  shards-gates violations      Tail violations.jsonl
+  shards-gates force-close     Force-close an open gate (and reset auto-verify) — operator override
+`);
+}

package/tools/shards-sessions.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// shards-sessions — list, inspect, resume, and end Shards chat sessions.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const sessionIndex = require('../src/ui/session-index.js');
+
+const PROJECT_DIR = process.cwd();
+const SHARDS_DIR = path.join(PROJECT_DIR, '.shards');
+const SESSIONS_DIR = path.join(SHARDS_DIR, 'sessions');
+const GATE_STATE_FILE = path.join(SHARDS_DIR, 'gates', 'state.json');
+
+// Mirrors src/ui/server.js#readGateSnapshot — returns the gate id (string) if a
+// gate is currently open, else null. Both code paths produce identical shapes
+// in INDEX.json, so the UI Sessions panel and CLI `show` render the same field.
+// Tolerant of a missing/corrupt state file (returns null silently).
+function readGateSnapshot() {
+  try {
+    const raw = fs.readFileSync(GATE_STATE_FILE, 'utf8');
+    const state = JSON.parse(raw);
+    if (state && state.open) {
+      return {
+        gateOpenAtEnd: state.id || null,
+        phase: typeof state.phase === 'number' ? state.phase : null,
+      };
+    }
+    return { gateOpenAtEnd: null, phase: null };
+  } catch {
+    return { gateOpenAtEnd: null, phase: null };
+  }
+}
+
+function formatDate(iso) {
+  if (!iso) return '—';
+  try { return new Date(iso).toLocaleString(); } catch { return iso; }
+}
+
+function formatRelative(iso) {
+  if (!iso) return '—';
+  const ms = Date.now() - Date.parse(iso);
+  if (!Number.isFinite(ms) || ms < 0) return iso;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h ago`;
+  const d = Math.round(h / 24);
+  return `${d}d ago`;
+}
+
+function short(id) {
+  return id ? id.slice(0, 8) : '—';
+}
+
+function pad(s, n) {
+  s = String(s == null ? '' : s);
+  if (s.length >= n) return s.slice(0, n);
+  return s + ' '.repeat(n - s.length);
+}
+
+// ─── Argument parsing ──────────────────────────────────────────────────────
+
+function parseFlags(argv) {
+  const out = { args: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > -1) {
+        out.flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) { out.flags[a.slice(2)] = next; i += 1; }
+        else { out.flags[a.slice(2)] = true; }
+      }
+    } else {
+      out.args.push(a);
+    }
+  }
+  return out;
+}
+
+function resolveSessionId(prefix, rows) {
+  // Allow operating on a unique short prefix — typing the full UUID is painful.
+  if (!prefix) return null;
+  const exact = rows.find((r) => r.sessionId === prefix);
+  if (exact) return exact.sessionId;
+  const matches = rows.filter((r) => r.sessionId.startsWith(prefix));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    console.error(`Ambiguous session prefix "${prefix}" — matched ${matches.length} sessions.`);
+    process.exit(2);
+  }
+  return matches[0].sessionId;
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────
+
+function cmdList(parsed) {
+  const filter = {};
+  if (parsed.flags.project) filter.project = parsed.flags.project;
+  if (parsed.flags.agent) filter.agent = parsed.flags.agent;
+  if (parsed.flags.status) filter.status = parsed.flags.status;
+
+  let rows = sessionIndex.listSessions(SESSIONS_DIR, filter);
+  const limit = parsed.flags.limit ? Number(parsed.flags.limit) : null;
+  if (limit && Number.isFinite(limit)) rows = rows.slice(0, limit);
+
+  if (rows.length === 0) {
+    console.log('\nNo sessions recorded.\n');
+    return;
+  }
+
+  console.log('');
+  console.log(pad('ID', 10) + pad('AGENT', 22) + pad('STATUS', 11) + pad('PHASE', 7) + pad('PROJECT', 28) + 'LAST');
+  console.log('─'.repeat(110));
+  for (const r of rows) {
+    console.log(
+      pad(short(r.sessionId), 10) +
+      pad(r.agent || '—', 22) +
+      pad(r.status, 11) +
+      pad(typeof r.phase === 'number' ? `${r.phase}` : '—', 7) +
+      pad(r.projectDir || r.projectName || '—', 28) +
+      formatRelative(r.lastActivityAt)
+    );
+  }
+  console.log('');
+  console.log(`${rows.length} session(s). Use \`shards-sessions show <id>\` for full detail.`);
+}
+
+function cmdShow(parsed) {
+  const all = sessionIndex.listSessions(SESSIONS_DIR);
+  const id = resolveSessionId(parsed.args[0], all);
+  if (!id) {
+    console.error(`No session matches "${parsed.args[0]}".`);
+    process.exit(1);
+  }
+  const entry = sessionIndex.getEntry(SESSIONS_DIR, id);
+  if (!entry) {
+    console.error('Entry vanished.');
+    process.exit(1);
+  }
+  console.log('');
+  console.log(`Session:    ${entry.sessionId}`);
+  console.log(`Agent:      ${entry.agent || '—'}`);
+  console.log(`Project:    ${entry.projectDir || entry.projectName || '—'}`);
+  console.log(`Status:     ${entry.status}`);
+  console.log(`Phase:      ${entry.phase == null ? '—' : entry.phase}`);
+  console.log(`Created:    ${formatDate(entry.createdAt)}`);
+  console.log(`Last act:   ${formatDate(entry.lastActivityAt)}  (${formatRelative(entry.lastActivityAt)})`);
+  if (entry.endedAt) console.log(`Ended:      ${formatDate(entry.endedAt)}  (reason: ${entry.endReason || '—'})`);
+  if (entry.gateOpenAtEnd) console.log(`Open gate:  ${entry.gateOpenAtEnd}`);
+  if (entry.resumedFrom) console.log(`Resumed:    from ${entry.resumedFrom}`);
+  if (entry.messageCount) console.log(`Messages:   ${entry.messageCount}`);
+  if (entry.lastUserPrompt) {
+    console.log('');
+    console.log('Last prompt:');
+    console.log(`  ${entry.lastUserPrompt}`);
+  }
+  console.log('');
+}
+
+function cmdResume(parsed) {
+  const all = sessionIndex.listSessions(SESSIONS_DIR);
+  const id = resolveSessionId(parsed.args[0], all);
+  if (!id) {
+    console.error(`No session matches "${parsed.args[0]}".`);
+    process.exit(1);
+  }
+  const entry = sessionIndex.getEntry(SESSIONS_DIR, id);
+  if (!entry) {
+    console.error('Entry not found.');
+    process.exit(1);
+  }
+  if (entry.status === 'active') {
+    console.error('That session is still marked active. End it first with `shards-sessions end <id>` or via the UI.');
+    process.exit(1);
+  }
+
+  // We can't re-exec claude from inside this process and have it land in the
+  // user's terminal, so print the exact command they need to run. This also
+  // works cleanly inside a Claude Code session — the user can copy-paste.
+  console.log('');
+  console.log(`To resume this session, run:`);
+  console.log('');
+  console.log(`  claude --resume ${entry.sessionId}`);
+  console.log('');
+  console.log(`(agent: ${entry.agent || '—'}, project: ${entry.projectDir || entry.projectName || '—'}, phase: ${entry.phase == null ? '—' : entry.phase})`);
+  console.log('');
+}
+
+function cmdEnd(parsed) {
+  const all = sessionIndex.listSessions(SESSIONS_DIR);
+  const id = resolveSessionId(parsed.args[0], all);
+  if (!id) {
+    console.error(`No session matches "${parsed.args[0]}".`);
+    process.exit(1);
+  }
+  const entry = sessionIndex.getEntry(SESSIONS_DIR, id);
+  if (!entry) {
+    console.error('Entry not found.');
+    process.exit(1);
+  }
+  if (entry.status !== 'active') {
+    console.log(`Session ${short(id)} is already ${entry.status}.`);
+    return;
+  }
+  // Snapshot gate state at end-of-session so CLI-ended sessions match the
+  // shape written by the UI's POST /chat/end path (src/ui/server.js).
+  const snap = readGateSnapshot();
+  sessionIndex.markEnded(SESSIONS_DIR, id, {
+    reason: 'cli_end',
+    gateOpenAtEnd: snap.gateOpenAtEnd,
+  });
+  if (typeof snap.phase === 'number') {
+    sessionIndex.updatePhase(SESSIONS_DIR, id, snap.phase);
+  }
+  console.log(`Marked session ${short(id)} as ended in the index.`);
+  if (snap.gateOpenAtEnd) console.log(`Captured open gate at end: ${snap.gateOpenAtEnd}`);
+  console.log(`Note: this does not kill a live claude process — if one is running for this session, end it from its terminal or the UI.`);
+}
+
+function cmdHelp() {
+  console.log(`
+shards-sessions — list, inspect, resume, and end Shards chat sessions
+
+Usage:
+  shards-sessions list [--status active|ended|abandoned] [--agent <name>] [--project <dir>] [--limit N]
+  shards-sessions show <id|prefix>
+  shards-sessions resume <id|prefix>      Prints the \`claude --resume\` command to run
+  shards-sessions end <id|prefix>         Marks an active entry as ended in INDEX.json
+
+Tips:
+  Session IDs accept any unique prefix (typically 8 chars is plenty).
+  All commands operate on .shards/sessions/INDEX.json in the current directory.
+`);
+}
+
+// ─── Dispatch ──────────────────────────────────────────────────────────────
+
+const raw = process.argv.slice(2);
+const cmd = raw[0] || 'list';
+const parsed = parseFlags(raw.slice(1));
+
+switch (cmd) {
+  case 'list': cmdList(parsed); break;
+  case 'show': cmdShow(parsed); break;
+  case 'resume': cmdResume(parsed); break;
+  case 'end': cmdEnd(parsed); break;
+  case 'help':
+  case '--help':
+  case '-h':
+    cmdHelp(); break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    cmdHelp();
+    process.exit(2);
+}