amicus 1.0.0

package/src/sidecar/progress.js

@@ -0,0 +1,218 @@
+/**
+ * Sidecar Progress Reader
+ *
+ * Reads conversation.jsonl and progress.json from a session directory
+ * and returns progress info: message count, last activity time, latest action,
+ * and lifecycle stage.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Lifecycle stage labels */
+const STAGE_LABELS = {
+  initializing: 'Starting OpenCode server...',
+  server_ready: 'Server ready, creating session...',
+  session_created: 'Session created',
+  prompt_sent: 'Briefing delivered, waiting for response...',
+  receiving: 'Generating response...',
+  complete: 'Complete'
+};
+
+/**
+ * Extract the latest action description from parsed JSONL entries.
+ *
+ * @param {object[]} entries - Parsed JSONL entries
+ * @returns {string} Short description of last assistant action
+ */
+function extractLatest(entries) {
+  const assistantEntries = entries.filter(e => e.role === 'assistant');
+
+  if (assistantEntries.length === 0) {
+    return 'Starting up...';
+  }
+
+  const last = assistantEntries[assistantEntries.length - 1];
+
+  // Tool use entry with name
+  if (last.toolCall && last.toolCall.name) {
+    return `Using ${last.toolCall.name}`;
+  }
+
+  // Text content: take first line, truncate to 80 chars
+  if (last.content) {
+    const firstLine = String(last.content).split('\n')[0];
+    if (!firstLine) {
+      return 'Working...';
+    }
+    if (firstLine.length > 80) {
+      return firstLine.slice(0, 80) + '...';
+    }
+    return firstLine;
+  }
+
+  // Tool use entry without name (SDK may not populate part.name)
+  if (last.type === 'tool_use' || last.toolCall) {
+    return 'Executing tool call...';
+  }
+
+  // Assistant entry exists but has no recognizable content
+  return 'Working...';
+}
+
+/**
+ * Compute a relative time string from a file mtime.
+ *
+ * @param {Date|null|undefined} mtime - File modification time
+ * @returns {string} Relative time (e.g., "12s ago", "3m ago", "2h ago", "never")
+ */
+function computeLastActivity(mtime) {
+  if (!mtime) {
+    return 'never';
+  }
+
+  const diffMs = Date.now() - mtime.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+
+  if (diffSec < 60) {
+    return `${diffSec}s ago`;
+  }
+
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) {
+    return `${diffMin}m ago`;
+  }
+
+  const diffHr = Math.floor(diffMin / 60);
+  return `${diffHr}h ago`;
+}
+
+/**
+ * Write a progress update to progress.json.
+ *
+ * @param {string} sessionDir - Path to the session directory
+ * @param {string} stage - Lifecycle stage name
+ * @param {object} [extra={}] - Additional fields (e.g., messagesReceived)
+ */
+function writeProgress(sessionDir, stage, extra = {}) {
+  const progressPath = path.join(sessionDir, 'progress.json');
+  const data = {
+    stage,
+    stageLabel: STAGE_LABELS[stage] || stage,
+    updatedAt: new Date().toISOString(),
+    ...extra
+  };
+  fs.writeFileSync(progressPath, JSON.stringify(data), { mode: 0o600 });
+}
+
+/**
+ * Read progress from a session's conversation.jsonl and progress.json files.
+ *
+ * @param {string} sessionDir - Path to the session directory
+ * @returns {{ messages: number, lastActivity: string, latest: string, stage?: string }}
+ */
+function readProgress(sessionDir) {
+  const convPath = path.join(sessionDir, 'conversation.jsonl');
+  const progressPath = path.join(sessionDir, 'progress.json');
+
+  let convStat = null;
+  const entries = [];
+
+  // Read conversation.jsonl if it exists
+  if (fs.existsSync(convPath)) {
+    convStat = fs.statSync(convPath);
+    const content = fs.readFileSync(convPath, 'utf-8');
+
+    for (const line of content.split('\n')) {
+      if (!line.trim()) {
+        continue;
+      }
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  }
+
+  // Count assistant messages from conversation.jsonl
+  let messages = entries.filter(e => e.role === 'assistant').length;
+
+  // Extract latest action from conversation.jsonl
+  let latest = extractLatest(entries);
+
+  // Determine lastActivity from conversation.jsonl mtime
+  let lastActivity = convStat
+    ? computeLastActivity(convStat.mtime)
+    : 'never';
+
+  // Read progress.json for lifecycle stage info
+  let stage;
+
+  if (fs.existsSync(progressPath)) {
+    try {
+      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
+      stage = progress.stage;
+
+      // Use progress stage label when no assistant entries exist yet
+      if (messages === 0 && progress.stageLabel) {
+        latest = progress.stageLabel;
+      }
+
+      // Use progress.json latestTool for better latest when extractLatest
+      // returns a generic fallback (tool_use entries without name)
+      if (messages > 0 && progress.latestTool && (latest === 'Working...' || latest === 'Executing tool call...')) {
+        latest = `Calling tool: ${progress.latestTool}`;
+      }
+
+      // Use messagesReceived from progress when conversation has no assistant entries
+      if (messages === 0 && progress.messagesReceived !== undefined) {
+        messages = progress.messagesReceived;
+      }
+
+      // Use progress updatedAt for lastActivity if more recent
+      if (progress.updatedAt) {
+        const progressTime = new Date(progress.updatedAt);
+        if (!convStat || progressTime > convStat.mtime) {
+          lastActivity = computeLastActivity(progressTime);
+        }
+      }
+    } catch {
+      // Ignore malformed progress file
+    }
+  }
+
+  // Compute raw lastActivityMs for stall detection
+  let lastActivityMs = null;
+  if (convStat) {
+    lastActivityMs = Date.now() - convStat.mtime.getTime();
+  }
+  // Use progress.json updatedAt if more recent
+  if (fs.existsSync(progressPath)) {
+    try {
+      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
+      if (progress.updatedAt) {
+        const progressMs = Date.now() - new Date(progress.updatedAt).getTime();
+        if (lastActivityMs === null || progressMs < lastActivityMs) {
+          lastActivityMs = progressMs;
+        }
+      }
+    } catch {
+      // Ignore — already handled above
+    }
+  }
+
+  const result = { messages, lastActivity, latest, lastActivityMs };
+  if (stage !== undefined) {
+    result.stage = stage;
+  }
+  return result;
+}
+
+module.exports = {
+  readProgress,
+  writeProgress,
+  extractLatest,
+  computeLastActivity,
+  STAGE_LABELS
+};

package/src/sidecar/read.js

@@ -0,0 +1,183 @@
+/**
+ * Sidecar Read Operations Module
+ *
+ * Handles reading and listing sidecar sessions.
+ * Spec Reference: §4.2, §4.5
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeSessionDir, TASK_ID_PATTERN } = require('../utils/validators');
+const { SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('../session-manager');
+
+/**
+ * Format a timestamp as relative age
+ * @param {string} dateStr - ISO date string
+ * @returns {string} Relative age (e.g., "30m ago", "5h ago", "3d ago")
+ */
+function formatAge(dateStr) {
+  const diff = Date.now() - new Date(dateStr).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 60) {
+    return `${mins}m ago`;
+  }
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+/**
+ * Enumerate sessions across canonical + legacy roots (dedup, amicus wins).
+ * @param {string} project
+ * @param {{status?: string}} [opts] - status filter ('running', etc.); omit/'all' for all
+ * @returns {Array<{id, model, status, agent, briefing, createdAt}>}
+ */
+function enumerateSessions(project, opts = {}) {
+  const roots = [SESSIONS_DIR, LEGACY_SESSIONS_DIR]
+    .map(d => path.join(project, '.claude', d))
+    .filter(fs.existsSync);
+
+  const byId = new Map();
+  for (const root of roots) {
+    for (const d of fs.readdirSync(root)) {
+      if (!TASK_ID_PATTERN.test(d)) { continue; }
+      if (byId.has(d)) { continue; }
+      const metaPath = path.join(root, d, 'metadata.json');
+      if (!fs.existsSync(metaPath)) { continue; }
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        byId.set(d, {
+          id: d, model: meta.model, status: meta.status, agent: meta.agent,
+          briefing: meta.briefing, createdAt: meta.createdAt,
+          type: meta.type || 'run',
+          parentWave: meta.parentWave || null,
+          legCount: Array.isArray(meta.legs) ? meta.legs.length : null,
+        });
+      } catch { /* skip unreadable */ }
+    }
+  }
+
+  let sessions = Array.from(byId.values())
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  if (opts.status && opts.status !== 'all') {
+    sessions = sessions.filter(s => s.status === opts.status);
+  }
+  return sessions;
+}
+
+/**
+ * List previous sidecar sessions
+ * Spec Reference: §4.2
+ *
+ * @param {object} options
+ * @param {string} [options.status] - Filter by status (all, running, complete)
+ * @param {boolean} [options.json] - Output as JSON
+ * @param {string} [options.project] - Project directory
+ */
+async function listSidecars(options) {
+  const { status, json, project = process.cwd() } = options;
+
+  const sessions = enumerateSessions(project, { status });
+  if (sessions.length === 0) {
+    console.log('No amicus sessions found.');
+    return;
+  }
+
+  if (json) {
+    console.log(JSON.stringify(sessions, null, 2));
+  } else {
+    console.log('ID        MODEL                  STATUS     AGE         BRIEFING');
+    console.log('─'.repeat(80));
+    sessions.forEach(s => {
+      const age = formatAge(s.createdAt);
+      const briefingShort = (s.briefing || '').slice(0, 30) +
+        ((s.briefing?.length > 30) ? '...' : '');
+      console.log(
+        `${(s.id || '').padEnd(10)}` +
+        `${(s.type === 'wave' ? `wave(${s.legCount ?? 0} legs)` : (s.model || '')).padEnd(23)}` +
+        `${(s.status || 'unknown').padEnd(11)}` +
+        `${age.padEnd(12)}` +
+        `${briefingShort}`
+      );
+    });
+  }
+}
+
+/**
+ * Read sidecar session data
+ * Spec Reference: §4.5
+ *
+ * @param {object} options
+ * @param {string} options.taskId - Task ID to read
+ * @param {boolean} [options.conversation] - Read conversation
+ * @param {boolean} [options.metadata] - Read metadata
+ * @param {string} [options.project] - Project directory
+ */
+async function readSidecar(options) {
+  const { taskId, conversation, metadata, json, project = process.cwd() } = options;
+
+  const sessionDir = safeSessionDir(project, taskId);
+
+  if (!fs.existsSync(sessionDir)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+
+  const metaPath = path.join(sessionDir, 'metadata.json');
+  let meta = {};
+  try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* legacy/partial */ }
+
+  if (json) {
+    const { buildRunResultFromSession, buildWaveResultFromSession } = require('../utils/result-schema');
+    const doc = meta.type === 'wave'
+      ? buildWaveResultFromSession(project, taskId)
+      : buildRunResultFromSession(project, taskId);
+    console.log(JSON.stringify(doc, null, 2));
+    return;
+  }
+
+  if (meta.type === 'wave' && !conversation && !metadata) {
+    const { buildWaveResultFromSession } = require('../utils/result-schema');
+    const { formatWaveHuman } = require('./fanout-output');
+    console.log(formatWaveHuman(buildWaveResultFromSession(project, taskId)));
+    return;
+  }
+
+  if (conversation) {
+    const convPath = path.join(sessionDir, 'conversation.jsonl');
+    if (fs.existsSync(convPath)) {
+      const lines = fs.readFileSync(convPath, 'utf-8').split('\n').filter(Boolean);
+      lines.forEach(line => {
+        try {
+          const msg = JSON.parse(line);
+          const time = new Date(msg.timestamp).toLocaleTimeString();
+          console.log(`[${msg.role} @ ${time}] ${msg.content}\n`);
+        } catch {
+          // Skip malformed lines
+        }
+      });
+    } else {
+      console.log('No conversation recorded.');
+    }
+  } else if (metadata) {
+    const metaPath = path.join(sessionDir, 'metadata.json');
+    console.log(fs.readFileSync(metaPath, 'utf-8'));
+  } else {
+    // Default: show summary
+    const summaryPath = path.join(sessionDir, 'summary.md');
+    if (fs.existsSync(summaryPath)) {
+      console.log(fs.readFileSync(summaryPath, 'utf-8'));
+    } else {
+      console.log('No summary available (session may not have been folded).');
+    }
+  }
+}
+
+module.exports = {
+  formatAge,
+  enumerateSessions,
+  listSidecars,
+  readSidecar
+};

package/src/sidecar/resume.js

@@ -0,0 +1,221 @@
+/**
+ * Sidecar Resume Operations - Handles resuming previous sidecar sessions
+ * Spec Reference: §4.3, §8.3
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { runInteractive, buildMcpConfig } = require('./start');
+const {
+  SessionPaths,
+  finalizeSession,
+  outputSummary,
+  createHeartbeat,
+  checkSessionLiveness
+} = require('./session-utils');
+const { acquireLock, releaseLock } = require('../utils/session-lock');
+const { runHeadless } = require('../headless');
+const { logger } = require('../utils/logger');
+
+/** Load session metadata from session directory */
+function loadSessionMetadata(sessionDir) {
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Session metadata not found: ${metaPath}`);
+  }
+  return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+}
+
+/** Load initial context (system prompt) from session */
+function loadInitialContext(sessionDir) {
+  const contextPath = SessionPaths.contextFile(sessionDir);
+  if (fs.existsSync(contextPath)) {
+    return fs.readFileSync(contextPath, 'utf-8');
+  }
+  return '';
+}
+
+/** Check for file drift - files that were read may have changed */
+function checkFileDrift(metadata, project) {
+  const filesRead = metadata.filesRead || [];
+  const lastActivity = metadata.completedAt || metadata.createdAt;
+  const lastActivityTime = new Date(lastActivity).getTime();
+  const changedFiles = [];
+
+  for (const file of filesRead) {
+    const filePath = path.join(project, file);
+    if (fs.existsSync(filePath)) {
+      const stat = fs.statSync(filePath);
+      if (stat.mtimeMs > lastActivityTime) {
+        changedFiles.push(file);
+      }
+    }
+  }
+
+  return { hasChanges: changedFiles.length > 0, changedFiles, lastActivityTime };
+}
+
+/** Build drift warning message */
+function buildDriftWarning(changedFiles, lastActivityTime) {
+  const timeSince = Date.now() - lastActivityTime;
+  const hours = Math.floor(timeSince / 3600000);
+
+  return `
+## ⚠️ RESUME NOTICE
+
+This session is being resumed after a pause. **The file system has changed since your last message.**
+
+**Time since last activity:** ${hours > 0 ? hours + ' hours' : 'Less than an hour'}
+
+**Changed files:**
+${changedFiles.map(f => `- ${f}`).join('\n')}
+
+Please verify your previous findings against the current state of these files before continuing.
+`;
+}
+
+/** Build user message for headless resume, including conversation history */
+function buildResumeUserMessage(briefing, conversation) {
+  const parts = [];
+
+  if (conversation) {
+    parts.push('## PREVIOUS CONVERSATION\n');
+    parts.push(conversation);
+    parts.push('\n---\n');
+    parts.push('## RESUME\n');
+    parts.push('You are resuming a previous session. Continue from where you left off.');
+  }
+
+  if (briefing) {
+    if (parts.length === 0) {
+      parts.push(briefing);
+    } else {
+      parts.push(`\nOriginal task: ${briefing}`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+/** Update session metadata status */
+function updateSessionStatus(sessionDir, status) {
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  meta.status = status;
+  if (status === 'running') {
+    meta.resumedAt = new Date().toISOString();
+  }
+  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+  return meta;
+}
+
+/** Resume a previous sidecar session - Spec Reference: §4.3, §8.3 */
+async function resumeSidecar(options) {
+  const {
+    taskId, project = process.cwd(), headless = false, timeout = 15,
+    mcp, mcpConfig, client, noMcp, excludeMcp
+  } = options;
+
+  // Resume operates on an EXISTING session — resolve dual-dir (amicus, then legacy).
+  const sessionDir = SessionPaths.resolveSessionDir(project, taskId);
+  if (!fs.existsSync(sessionDir)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+
+  // Load previous session data
+  const metadata = loadSessionMetadata(sessionDir);
+  const systemPrompt = loadInitialContext(sessionDir);
+
+  // Dead-process detection: log if the previous process is no longer alive
+  const liveness = checkSessionLiveness(metadata);
+  if (liveness !== 'alive') {
+    logger.info('Session process is dead, restoring from disk', {
+      taskId, liveness, pid: metadata.pid,
+    });
+  }
+
+  // Acquire lock to prevent concurrent resume operations
+  acquireLock(sessionDir, headless ? 'headless' : 'interactive');
+
+  let heartbeat;
+  try {
+    const mcpServers = buildMcpConfig({ mcp, mcpConfig, clientType: client, noMcp, excludeMcp });
+    logger.info('Resuming session', { taskId, model: metadata.model, briefing: metadata.briefing });
+    // Inherited model: advisory only (F5) — never block reopening a session.
+    const { warnIfNotInCatalog } = require('../utils/model-validator');
+    await warnIfNotInCatalog(metadata.model);
+
+    // Check for file drift
+    const drift = checkFileDrift(metadata, project);
+    let resumePrompt = systemPrompt;
+
+    if (drift.hasChanges) {
+      const driftWarning = buildDriftWarning(drift.changedFiles, drift.lastActivityTime);
+      resumePrompt = systemPrompt + '\n' + driftWarning;
+      logger.warn('Files changed since last activity', { taskId, changedFileCount: drift.changedFiles.length });
+    }
+
+    // Update metadata (get updated metadata with resumedAt)
+    const updatedMetadata = updateSessionStatus(sessionDir, 'running');
+
+    // Start heartbeat
+    heartbeat = createHeartbeat();
+
+    let summary;
+    const effectiveAgent = metadata.agent || 'Build';
+
+    // Load conversation for both paths (interactive already did this, headless didn't)
+    const conversationPath = SessionPaths.conversationFile(sessionDir);
+    const existingConversation = fs.existsSync(conversationPath)
+      ? fs.readFileSync(conversationPath, 'utf-8')
+      : '';
+
+    if (headless) {
+      const userMessage = buildResumeUserMessage(metadata.briefing || '', existingConversation);
+      const result = await runHeadless(
+        metadata.model, resumePrompt, userMessage,
+        taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers }
+      );
+      summary = result.summary || '## Sidecar Results: No Output\n\nResumed session completed without summary.';
+
+      if (result.timedOut) { logger.warn('Resume task timed out', { taskId }); }
+      if (result.error) { logger.error('Resume task error', { taskId, error: result.error }); }
+    } else {
+      logger.info('Launching interactive resume', { taskId, model: metadata.model });
+
+      const result = await runInteractive(
+        metadata.model, resumePrompt, metadata.briefing || '',
+        taskId, project,
+        {
+          agent: effectiveAgent,
+          isResume: true,
+          conversation: existingConversation,
+          opencodeSessionId: metadata.opencodeSessionId,
+          mcp: mcpServers
+        }
+      );
+      summary = result.summary || '';
+      if (result.error) { logger.error('Interactive resume error', { taskId, error: result.error }); }
+    }
+
+    // Output summary
+    outputSummary(summary);
+
+    // Finalize session (use updatedMetadata which has resumedAt)
+    finalizeSession(sessionDir, summary, project, updatedMetadata);
+  } finally {
+    if (heartbeat) { heartbeat.stop(); }
+    releaseLock(sessionDir);
+  }
+}
+
+module.exports = {
+  loadSessionMetadata,
+  loadInitialContext,
+  checkFileDrift,
+  buildDriftWarning,
+  buildResumeUserMessage,
+  updateSessionStatus,
+  resumeSidecar
+};