@jaimevalasek/aioson 1.3.0 → 1.5.1

package/src/commands/runtime.js

@@ -13,8 +13,14 @@ const {
   attachArtifact,
   upsertContentItem,
   getStatusSnapshot,
-  logAgentEvent
+  logAgentEvent,
+  appendRunEvent,
+  readAgentSession,
+  clearAgentSession
 } = require('../runtime-store');
+const { runAutoDelivery } = require('../delivery-runner');
+const { writeHandoff, buildRuntimeLogHandoff } = require('../session-handoff');
+const { backupAiosonDocs, isDocCreatingAgent } = require('../backup-local');
 
 const ALLOWED_LAYOUTS = new Set(['document', 'tabs', 'accordion', 'stack', 'mixed']);
 const DEFAULT_TEXT_FIELDS = ['content', 'text', 'body', 'lyrics', 'markdown'];
@@ -31,6 +37,152 @@ function requireOption(options, key, t) {
   return String(value).trim();
 }
 
+function normalizeAgentHandle(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  return text.startsWith('@') ? text : `@${text}`;
+}
+
+function makeDirectSessionKey(agentName) {
+  return `direct-session:${Date.now()}:${String(agentName || '').replace(/^@/, '')}`;
+}
+
+function parseWatchSeconds(value) {
+  if (value === undefined || value === null || value === false) return null;
+  if (value === true || value === '') return 2;
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 2;
+  return parsed;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function collectRuntimeSessionSnapshot(db, runtimeDir, agentName, options = {}) {
+  const normalizedAgent = normalizeAgentHandle(agentName);
+  const eventLimit = Math.max(1, Math.min(Number(options.limit) || 8, 20));
+  const session = await readAgentSession(runtimeDir, normalizedAgent);
+  const activeSession = session && !session.finished ? session : null;
+
+  let run = null;
+  if (activeSession && activeSession.runKey) {
+    run = db.prepare(`
+      SELECT
+        run_key, task_key, agent_name, agent_kind, squad_slug, session_key, source,
+        title, status, summary, output_path, started_at, updated_at, finished_at
+      FROM agent_runs
+      WHERE run_key = ?
+      LIMIT 1
+    `).get(activeSession.runKey);
+  }
+
+  if (!run) {
+    run = db.prepare(`
+      SELECT
+        run_key, task_key, agent_name, agent_kind, squad_slug, session_key, source,
+        title, status, summary, output_path, started_at, updated_at, finished_at
+      FROM agent_runs
+      WHERE agent_name = ?
+      ORDER BY updated_at DESC, started_at DESC
+      LIMIT 1
+    `).get(normalizedAgent);
+  }
+
+  const task = run && run.task_key
+    ? db.prepare(`
+        SELECT
+          task_key, squad_slug, session_key, title, goal, status, created_by, created_at, updated_at, finished_at
+        FROM tasks
+        WHERE task_key = ?
+        LIMIT 1
+      `).get(run.task_key)
+    : null;
+
+  const recentEvents = run
+    ? db.prepare(`
+        SELECT event_type, phase, status, message, created_at
+        FROM execution_events
+        WHERE run_key = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(run.run_key, eventLimit).reverse()
+    : [];
+
+  const open = Boolean(activeSession && run && (run.status === 'running' || run.status === 'queued'));
+  const state = open ? 'open' : (run ? 'closed' : 'idle');
+
+  return {
+    agent: normalizedAgent,
+    state,
+    open,
+    sessionKey: activeSession?.sessionKey || run?.session_key || task?.session_key || null,
+    startedAt: activeSession?.startedAt || run?.started_at || task?.created_at || null,
+    updatedAt: run?.updated_at || task?.updated_at || null,
+    session: activeSession,
+    run,
+    task,
+    recentEvents
+  };
+}
+
+async function getRuntimeSessionSnapshot(targetDir, agentName, t, options = {}) {
+  const { dbPath, runtimeDir } = resolveRuntimePaths(targetDir);
+
+  if (!(await runtimeStoreExists(targetDir))) {
+    throw new Error(t('runtime.store_missing', { path: dbPath }));
+  }
+
+  const { db } = await openRuntimeDb(targetDir, { mustExist: true });
+  try {
+    const snapshot = await collectRuntimeSessionSnapshot(db, runtimeDir, agentName, options);
+    return {
+      ok: true,
+      targetDir,
+      dbPath,
+      ...snapshot
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function printRuntimeSessionSnapshot(snapshot, logger) {
+  logger.log(`Direct session: ${snapshot.agent}`);
+  logger.log(`State: ${snapshot.state}`);
+
+  if (snapshot.sessionKey) {
+    logger.log(`Session: ${snapshot.sessionKey}`);
+  }
+
+  if (snapshot.task) {
+    logger.log(`Task: ${snapshot.task.task_key} | status: ${snapshot.task.status} | work: ${snapshot.task.title || '—'}`);
+  }
+
+  if (snapshot.run) {
+    logger.log(`Run: ${snapshot.run.run_key} | status: ${snapshot.run.status} | work: ${snapshot.run.title || snapshot.run.summary || '—'}`);
+  }
+
+  if (snapshot.startedAt) {
+    logger.log(`Started: ${snapshot.startedAt}`);
+  }
+
+  if (snapshot.updatedAt) {
+    logger.log(`Updated: ${snapshot.updatedAt}`);
+  }
+
+  if (snapshot.recentEvents.length === 0) {
+    logger.log('Recent events: none');
+    return;
+  }
+
+  logger.log('Recent events:');
+  for (const event of snapshot.recentEvents) {
+    logger.log(`- ${event.created_at} | ${event.event_type} | ${event.message || '—'}`);
+  }
+}
+
 async function readJsonIfExists(filePath) {
   try {
     const raw = await fs.readFile(filePath, 'utf8');
@@ -418,6 +570,14 @@ async function ingestContentCandidate(db, targetDir, absolutePath, options = {})
       createdByAgent: options.agent || content.createdByAgent || content.created_by_agent || null
     });
 
+    // Fire auto-delivery if configured (non-blocking)
+    runAutoDelivery(db, {
+      projectDir: targetDir,
+      squadSlug,
+      contentKey: content.contentKey,
+      contentPayload: content
+    }).catch(() => {}); // Swallow errors — delivery failure should not break ingestion
+
     return { indexed: true, kind: 'content-json', contentKey: content.contentKey };
   }
 
@@ -458,6 +618,14 @@ async function ingestContentCandidate(db, targetDir, absolutePath, options = {})
     createdByAgent: options.agent || null
   });
 
+  // Fire auto-delivery if configured (non-blocking)
+  runAutoDelivery(db, {
+    projectDir: targetDir,
+    squadSlug,
+    contentKey: payload.contentKey,
+    contentPayload: payload
+  }).catch(() => {}); // Swallow errors — delivery failure should not break ingestion
+
   return { indexed: true, kind: path.extname(absolutePath).toLowerCase(), contentKey: payload.contentKey };
 }
 
@@ -820,6 +988,11 @@ async function runRuntimeStatus({ args, options = {}, logger, t }) {
       recentTasks: snapshot.recentTasks,
       activeRuns: snapshot.activeRuns,
       recentRuns: snapshot.recentRuns,
+      activeLiveSessions: snapshot.activeLiveSessions,
+      activeMicroTasks: snapshot.activeMicroTasks,
+      recentLiveSessions: snapshot.recentLiveSessions,
+      recentMicroTasks: snapshot.recentMicroTasks,
+      recentHandoffs: snapshot.recentHandoffs,
       recentArtifacts: snapshot.recentArtifacts,
       recentContentItems: snapshot.recentContentItems,
       recentExecutionEvents: snapshot.recentExecutionEvents
@@ -874,6 +1047,49 @@ async function runRuntimeStatus({ args, options = {}, logger, t }) {
           );
         }
       }
+      if (snapshot.activeLiveSessions.length > 0) {
+        logger.log(t('runtime.status_live_sessions_title'));
+        for (const task of snapshot.activeLiveSessions) {
+          logger.log(
+            t('runtime.status_live_session_line', {
+              task: task.task_key,
+              agent: task.latest_agent_name || task.created_by || '—',
+              status: task.status,
+              plan: task.plan_steps_total > 0 ? `${task.plan_steps_done}/${task.plan_steps_total}` : '—',
+              micro: `${task.completed_child_task_count || 0}/${task.child_task_count || 0}`,
+              handoffs: task.handoff_count || 0,
+              title: task.title || '—'
+            })
+          );
+        }
+      }
+      if (snapshot.activeMicroTasks.length > 0) {
+        logger.log(t('runtime.status_micro_tasks_title'));
+        for (const task of snapshot.activeMicroTasks) {
+          logger.log(
+            t('runtime.status_micro_task_line', {
+              task: task.task_key,
+              parent: task.parent_task_key || '—',
+              status: task.status,
+              title: task.title || task.goal || '—'
+            })
+          );
+        }
+      }
+      if (snapshot.recentHandoffs.length > 0) {
+        logger.log(t('runtime.status_handoffs_title'));
+        for (const event of snapshot.recentHandoffs.slice(0, 5)) {
+          logger.log(
+            t('runtime.status_handoff_line', {
+              created: event.created_at,
+              from: event.handoff_from || event.agent_name || '—',
+              to: event.handoff_to || '—',
+              session: event.session_key || '—',
+              message: event.message || '—'
+            })
+          );
+        }
+      }
     }
 
     return payload;
@@ -911,6 +1127,16 @@ async function runRuntimeLog({ args, options = {}, logger, t }) {
       meta: options.meta ? (() => { try { return JSON.parse(options.meta); } catch { return { raw: options.meta }; } })() : undefined
     });
 
+    // Generate session handoff on --finish
+    if (options.finish) {
+      const handoffData = buildRuntimeLogHandoff(
+        agentName,
+        options.message || '',
+        options.summary || ''
+      );
+      await writeHandoff(targetDir, handoffData);
+    }
+
     if (!options.json) {
       const isFinish = Boolean(options.finish);
       logger.log(isFinish
@@ -933,6 +1159,842 @@ async function runRuntimeLog({ args, options = {}, logger, t }) {
   }
 }
 
+
+/**
+ * aioson agent:done . --agent=<name> --summary="..." [--title="..."] [--status=completed|failed]
+ *
+ * Safe self-registration for official agents invoked directly (not via workflow:next or live:start).
+ * - If an active live session exists for the agent: appends a completion event without closing the session.
+ * - If no session exists: creates a standalone task+run and immediately marks it completed.
+ *
+ * Intended to be called ONCE at the very end of an agent session, after delivering the main artifact.
+ */
+async function runAgentDone({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agentName = String(options.agent || '').trim();
+  if (!agentName) {
+    throw new Error('--agent is required');
+  }
+  const normalizedAgent = agentName.startsWith('@') ? agentName : `@${agentName}`;
+  const summary = String(options.summary || options.message || `${normalizedAgent} session completed`).trim();
+  const title = options.title ? String(options.title).trim() : null;
+  const status = options.status || 'completed';
+
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  try {
+    const session = await readAgentSession(runtimeDir, normalizedAgent);
+    const hasActiveSession = session && !session.finished && session.runKey;
+
+    if (hasActiveSession) {
+      // Live or tracked session is already open — only append a completion note.
+      // Do NOT close the session: live:handoff or live:close owns the lifecycle.
+      appendRunEvent(db, {
+        runKey: session.runKey,
+        eventType: 'agent_done',
+        phase: 'live',
+        status: 'running',
+        message: summary
+      });
+
+      if (!options.json) {
+        logger.log(`agent:done — ${normalizedAgent} | live session active, event logged | run: ${session.runKey} (${dbPath})`);
+      }
+
+      if (isDocCreatingAgent(normalizedAgent)) {
+        backupAiosonDocs(targetDir).catch(() => {});
+      }
+
+      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey };
+    }
+
+    // No active session — create a standalone task+run and immediately complete it.
+    const { runKey, taskKey } = await logAgentEvent(db, runtimeDir, {
+      agentName: normalizedAgent,
+      message: summary,
+      type: 'completed',
+      taskTitle: title || normalizedAgent,
+      finish: true,
+      status,
+      summary
+    });
+
+    if (!options.json) {
+      logger.log(`agent:done — ${normalizedAgent} | task: ${taskKey} | run: ${runKey} (${dbPath})`);
+    }
+
+    if (isDocCreatingAgent(normalizedAgent)) {
+      backupAiosonDocs(targetDir).catch(() => {});
+    }
+
+    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey };
+  } finally {
+    db.close();
+  }
+}
+
+
+async function runRuntimeSessionStart({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  try {
+    const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
+    const existingSnapshot = await collectRuntimeSessionSnapshot(db, runtimeDir, agentName, { limit: options.limit });
+
+    if (existingSnapshot.session && !existingSnapshot.open) {
+      await clearAgentSession(runtimeDir, agentName);
+    }
+
+    if (existingSnapshot.open) {
+      if (!options.json) {
+        logger.log(`Direct session already active: ${agentName} | task: ${existingSnapshot.task?.task_key || '—'} | run: ${existingSnapshot.run?.run_key || '—'} (${dbPath})`);
+      }
+      return {
+        ok: true,
+        targetDir,
+        dbPath,
+        agent: agentName,
+        taskKey: existingSnapshot.task?.task_key || existingSnapshot.session?.taskKey || null,
+        runKey: existingSnapshot.run?.run_key || existingSnapshot.session?.runKey || null,
+        sessionKey: existingSnapshot.sessionKey,
+        status: existingSnapshot.run?.status || 'running',
+        reused: true,
+        open: true
+      };
+    }
+
+    const sessionKey = options.session ? String(options.session).trim() : makeDirectSessionKey(agentName);
+    const title = options.title ? String(options.title).trim() : `Direct session ${agentName}`;
+    const message = options.message ? String(options.message).trim() : `Session started for ${agentName}`;
+    const { runKey, taskKey } = await logAgentEvent(db, runtimeDir, {
+      agentName,
+      message,
+      type: options.type || 'session.start',
+      taskTitle: title,
+      sessionKey,
+      meta: options.meta ? (() => { try { return JSON.parse(options.meta); } catch { return { raw: options.meta }; } })() : undefined
+    });
+
+    if (!options.json) {
+      logger.log(`Direct session started: ${agentName} | task: ${taskKey} | run: ${runKey} (${dbPath})`);
+    }
+
+    return {
+      ok: true,
+      targetDir,
+      dbPath,
+      agent: agentName,
+      taskKey,
+      runKey,
+      sessionKey,
+      status: 'running',
+      reused: false,
+      open: true
+    };
+  } finally {
+    db.close();
+  }
+}
+
+async function runRuntimeSessionLog({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  try {
+    const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
+    const message = requireOption(options, 'message', t);
+    const existingSnapshot = await collectRuntimeSessionSnapshot(db, runtimeDir, agentName, { limit: options.limit });
+
+    if (existingSnapshot.session && !existingSnapshot.open) {
+      await clearAgentSession(runtimeDir, agentName);
+    }
+
+    const autoStarted = !existingSnapshot.open;
+    const sessionKey = existingSnapshot.sessionKey || (options.session ? String(options.session).trim() : makeDirectSessionKey(agentName));
+    const title = options.title ? String(options.title).trim() : `Direct session ${agentName}`;
+    const { runKey, taskKey } = await logAgentEvent(db, runtimeDir, {
+      agentName,
+      message,
+      type: options.type || 'session.log',
+      taskTitle: title,
+      sessionKey,
+      meta: options.meta ? (() => { try { return JSON.parse(options.meta); } catch { return { raw: options.meta }; } })() : undefined
+    });
+
+    if (!options.json) {
+      logger.log(`Direct session log recorded: ${agentName} | run: ${runKey} (${dbPath})`);
+    }
+
+    return {
+      ok: true,
+      targetDir,
+      dbPath,
+      agent: agentName,
+      taskKey,
+      runKey,
+      sessionKey,
+      status: 'running',
+      autoStarted,
+      open: true
+    };
+  } finally {
+    db.close();
+  }
+}
+
+async function runRuntimeSessionFinish({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  try {
+    const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
+    const existingSnapshot = await collectRuntimeSessionSnapshot(db, runtimeDir, agentName, { limit: options.limit });
+
+    if (!existingSnapshot.open) {
+      throw new Error(`No active direct session for ${agentName}.`);
+    }
+
+    const summary = options.summary ? String(options.summary).trim() : '';
+    const message = options.message ? String(options.message).trim() : (summary || `Session finished for ${agentName}`);
+    const { runKey, taskKey } = await logAgentEvent(db, runtimeDir, {
+      agentName,
+      message,
+      type: options.type || 'session.finish',
+      finish: true,
+      status: options.status || 'completed',
+      summary,
+      meta: options.meta ? (() => { try { return JSON.parse(options.meta); } catch { return { raw: options.meta }; } })() : undefined
+    });
+
+    if (!options.json) {
+      logger.log(`Direct session finished: ${agentName} | run: ${runKey} (${dbPath})`);
+    }
+
+    return {
+      ok: true,
+      targetDir,
+      dbPath,
+      agent: agentName,
+      taskKey,
+      runKey,
+      sessionKey: existingSnapshot.sessionKey,
+      status: options.status || 'completed',
+      finished: true,
+      open: false
+    };
+  } finally {
+    db.close();
+  }
+}
+
+async function runRuntimeSessionStatus({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agentName = normalizeAgentHandle(requireOption(options, 'agent', t));
+  const watchSeconds = parseWatchSeconds(options.watch);
+
+  if (watchSeconds && options.json) {
+    throw new Error('--watch cannot be combined with --json.');
+  }
+
+  if (!watchSeconds) {
+    const snapshot = await getRuntimeSessionSnapshot(targetDir, agentName, t, { limit: options.limit });
+    if (!options.json) {
+      printRuntimeSessionSnapshot(snapshot, logger);
+    }
+    return snapshot;
+  }
+
+  while (true) {
+    const snapshot = await getRuntimeSessionSnapshot(targetDir, agentName, t, { limit: options.limit });
+    if (process.stdout && process.stdout.isTTY) {
+      process.stdout.write('\x1Bc');
+    }
+    printRuntimeSessionSnapshot(snapshot, logger);
+    await sleep(Math.round(watchSeconds * 1000));
+  }
+}
+
+async function runDeliver({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const squadSlug = requireOption(options, 'squad', t);
+  const contentKey = options['content-key'] || options.contentKey || null;
+  const triggerType = options.trigger || 'manual';
+
+  const { db, dbPath } = await withRuntimeDb(targetDir, t);
+
+  try {
+    const { runManualDelivery } = require('../delivery-runner');
+
+    // Optionally load content payload from DB
+    let contentPayload = null;
+    if (contentKey) {
+      const row = db.prepare('SELECT payload_json FROM content_items WHERE content_key = ? AND squad_slug = ?').get(contentKey, squadSlug);
+      if (row && row.payload_json) {
+        try { contentPayload = JSON.parse(row.payload_json); } catch { /* ignore */ }
+      }
+    }
+
+    const result = await runManualDelivery(db, {
+      projectDir: targetDir,
+      squadSlug,
+      contentKey,
+      triggerType,
+      contentPayload
+    });
+
+    if (!result.delivered) {
+      logger.log(`Delivery skipped: ${result.reason}`);
+      return { ok: false, ...result };
+    }
+
+    for (const r of result.results || []) {
+      const status = r.ok ? 'OK' : 'FAIL';
+      logger.log(`  ${status} ${r.webhookSlug} — ${r.statusCode || 'no response'} (${r.attempts} attempt${r.attempts > 1 ? 's' : ''})`);
+      if (r.error) logger.log(`    Error: ${r.error}`);
+    }
+
+    logger.log(`\nDelivery ${result.allOk ? 'completed' : 'completed with errors'}.`);
+    return { ok: result.allOk, ...result };
+  } finally {
+    db.close();
+  }
+}
+
+async function findManifestPath(projectDir, slug) {
+  const candidates = [
+    path.join(projectDir, '.aioson', 'squads', slug, 'squad.manifest.json'),
+    path.join(projectDir, 'agents', slug, 'squad.manifest.json')
+  ];
+  for (const p of candidates) {
+    try { await fs.stat(p); return p; } catch { continue; }
+  }
+  return null;
+}
+
+async function runOutputStrategyExport({ args, options = {}, logger, t }) {
+  const projectDir = resolveTargetDir(args);
+  const slug = requireOption(options, 'squad', t);
+  const manifestPath = await findManifestPath(projectDir, slug);
+
+  if (!manifestPath) {
+    logger.error(`Manifest not found for squad "${slug}"`);
+    return { ok: false, error: 'Manifest not found' };
+  }
+
+  const raw = await fs.readFile(manifestPath, 'utf8');
+  const manifest = JSON.parse(raw);
+  const strategy = manifest.outputStrategy || null;
+
+  if (!strategy) {
+    logger.log(`Squad "${slug}" has no outputStrategy configured.`);
+    return { ok: false, error: 'No outputStrategy found' };
+  }
+
+  const exportsDir = path.join(projectDir, '.aioson', 'squads', 'exports');
+  await fs.mkdir(exportsDir, { recursive: true });
+  const outFile = path.join(exportsDir, `${slug}.output-strategy.json`);
+  await fs.writeFile(outFile, JSON.stringify(strategy, null, 2) + '\n', 'utf8');
+
+  const relOut = path.relative(projectDir, outFile).replace(/\\/g, '/');
+  logger.log(`Exported outputStrategy from "${slug}" → ${relOut}`);
+  return { ok: true, file: relOut, strategy };
+}
+
+async function runOutputStrategyImport({ args, options = {}, logger, t }) {
+  const projectDir = resolveTargetDir(args);
+  const slug = requireOption(options, 'squad', t);
+  const fromSlug = options.from || null;
+  const fromFile = options.file || null;
+
+  if (!fromSlug && !fromFile) {
+    logger.error('Usage: aioson output-strategy:import --squad=<target> --from=<source-slug> | --file=<path>');
+    return { ok: false, error: 'Provide --from or --file' };
+  }
+
+  // Load source strategy
+  let strategy;
+  if (fromFile) {
+    const absFile = path.resolve(projectDir, fromFile);
+    const raw = await fs.readFile(absFile, 'utf8');
+    strategy = JSON.parse(raw);
+  } else {
+    const srcPath = await findManifestPath(projectDir, fromSlug);
+    if (!srcPath) {
+      logger.error(`Source squad "${fromSlug}" manifest not found`);
+      return { ok: false, error: 'Source manifest not found' };
+    }
+    const srcManifest = JSON.parse(await fs.readFile(srcPath, 'utf8'));
+    strategy = srcManifest.outputStrategy || null;
+    if (!strategy) {
+      logger.error(`Source squad "${fromSlug}" has no outputStrategy`);
+      return { ok: false, error: 'Source has no outputStrategy' };
+    }
+  }
+
+  // Write to target
+  const targetPath = await findManifestPath(projectDir, slug);
+  if (!targetPath) {
+    logger.error(`Target squad "${slug}" manifest not found`);
+    return { ok: false, error: 'Target manifest not found' };
+  }
+
+  const targetManifest = JSON.parse(await fs.readFile(targetPath, 'utf8'));
+  targetManifest.outputStrategy = strategy;
+  await fs.writeFile(targetPath, JSON.stringify(targetManifest, null, 2) + '\n', 'utf8');
+
+  logger.log(`Imported outputStrategy into "${slug}" from ${fromSlug || fromFile}`);
+  return { ok: true, squad: slug, source: fromSlug || fromFile };
+}
+
+/**
+ * aioson devlog:sync [targetDir]
+ *
+ * Parses aioson-logs/devlog-*.md files, imports them into SQLite as
+ * task + run + events, then renames each file to .synced so it is not
+ * re-imported on subsequent runs.
+ */
+async function runDevlogSync({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const logsDir = path.join(targetDir, 'aioson-logs');
+
+  let entries;
+  try {
+    entries = await fs.readdir(logsDir);
+  } catch {
+    logger.log('No aioson-logs/ directory found — nothing to sync.');
+    return { ok: true, synced: 0 };
+  }
+
+  const devlogFiles = entries
+    .filter(f => f.startsWith('devlog-') && f.endsWith('.md'))
+    .sort();
+
+  if (devlogFiles.length === 0) {
+    logger.log('No devlog files to sync.');
+    return { ok: true, synced: 0 };
+  }
+
+  const { db, dbPath } = await openRuntimeDb(targetDir);
+  let synced = 0;
+  const parsedDevlogs = [];
+
+  try {
+    for (const file of devlogFiles) {
+      const filePath = path.join(logsDir, file);
+      const raw = await fs.readFile(filePath, 'utf8');
+
+      // Parse YAML frontmatter
+      const fm = parseFrontmatter(raw);
+      const agent = fm.agent || 'unknown';
+      const summary = fm.summary || file;
+      const sessionStart = fm.session_start || null;
+      const sessionEnd = fm.session_end || null;
+      const status = fm.status || 'completed';
+      const body = raw.replace(/^---[\s\S]*?---\s*/, '');
+
+      parsedDevlogs.push({ filename: file, agent, summary, sessionStart, sessionEnd, status, body });
+
+      // Create task + run
+      const taskKey = startTask(db, {
+        title: `devlog: ${summary}`,
+        squadSlug: null,
+        status: status === 'partial' ? 'running' : 'completed',
+        createdBy: agent
+      });
+
+      const runKey = startRun(db, {
+        taskKey,
+        agentName: agent,
+        agentKind: 'devlog',
+        squadSlug: null,
+        title: `@${agent} devlog`,
+        message: summary
+      });
+
+      // Extract body sections as events
+      const sections = body.split(/^## /m).filter(Boolean);
+      for (const section of sections) {
+        const firstLine = section.split('\n')[0].trim();
+        const content = section.slice(firstLine.length).trim();
+        if (content) {
+          appendRunEvent(db, {
+            runKey,
+            eventType: 'devlog',
+            phase: firstLine.toLowerCase().replace(/\s+/g, '_'),
+            status: 'completed',
+            message: `## ${firstLine}\n${content}`,
+            createdAt: sessionEnd || new Date().toISOString()
+          });
+        }
+      }
+
+      // Close the run
+      updateRun(db, runKey, {
+        status: status === 'partial' ? 'running' : 'completed',
+        summary,
+        finishedAt: sessionEnd || new Date().toISOString()
+      });
+
+      if (status !== 'partial') {
+        updateTask(db, taskKey, {
+          status: 'completed',
+          finishedAt: sessionEnd || new Date().toISOString()
+        });
+      }
+
+      // Rename to .synced
+      await fs.rename(filePath, filePath.replace(/\.md$/, '.synced.md'));
+      synced++;
+      logger.log(`  Synced: ${file} → task=${taskKey} run=${runKey}`);
+    }
+
+    logger.log(`Synced ${synced} devlog(s) into ${dbPath}`);
+
+    // Cloud sync
+    if (options.cloud) {
+      const cloudResult = await syncDevlogsToCloud(targetDir, parsedDevlogs, options, logger);
+      return { ok: true, synced, dbPath, cloud: cloudResult };
+    }
+
+    return { ok: true, synced, dbPath };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Sends parsed devlogs to the cloud endpoint.
+ * Reads cloud config from .aioson/install.json or --url / --token options.
+ */
+async function syncDevlogsToCloud(targetDir, devlogs, options, logger) {
+  const cloudUrl = options.url || options['cloud-url'] || await resolveCloudUrl(targetDir);
+  const cloudToken = options.token || options['cloud-token'] || await resolveCloudToken(targetDir);
+
+  if (!cloudUrl) {
+    logger.error('Cloud URL not configured. Use --url or set cloudBaseUrl in dashboard project settings.');
+    return { ok: false, error: 'missing_cloud_url' };
+  }
+  if (!cloudToken) {
+    logger.error('Cloud token not configured. Use --token or set cloudApiToken in dashboard project settings.');
+    return { ok: false, error: 'missing_cloud_token' };
+  }
+
+  const endpoint = `${cloudUrl.replace(/\/+$/, '')}/api/publish/runtime`;
+  const payload = {
+    tasks: [],
+    devlogs: devlogs.map(d => ({
+      filename: d.filename,
+      agent: d.agent,
+      sessionStart: d.sessionStart,
+      sessionEnd: d.sessionEnd,
+      status: d.status,
+      summary: d.summary,
+      body: d.body
+    }))
+  };
+
+  logger.log(`  Pushing ${devlogs.length} devlog(s) to ${endpoint}...`);
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'accept': 'application/json',
+      'content-type': 'application/json',
+      'authorization': `Bearer ${cloudToken}`
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(15000)
+  });
+
+  const text = await response.text();
+  let result;
+  try { result = JSON.parse(text); } catch { result = { ok: false, error: text }; }
+
+  if (result.ok) {
+    logger.log(`  Cloud sync OK: ${result.devlogsStored || 0} devlog(s) stored.`);
+  } else {
+    logger.error(`  Cloud sync failed: ${result.error || response.status}`);
+  }
+
+  return result;
+}
+
+async function resolveCloudUrl(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, '.aioson/install.json'), 'utf8');
+    const meta = JSON.parse(raw);
+    return meta.cloudBaseUrl || null;
+  } catch { return null; }
+}
+
+async function resolveCloudToken(targetDir) {
+  try {
+    const raw = await fs.readFile(path.join(targetDir, '.aioson/install.json'), 'utf8');
+    const meta = JSON.parse(raw);
+    return meta.cloudApiToken || null;
+  } catch { return null; }
+}
+
+/**
+ * Minimal YAML frontmatter parser (no external deps).
+ * Returns an object with frontmatter keys, or {} if none.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let val = line.slice(idx + 1).trim();
+    // Strip surrounding quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    result[key] = val;
+  }
+  return result;
+}
+
+/**
+ * Parses a duration string like "24h", "30m", "7d" into milliseconds.
+ * Falls back to treating the raw value as hours.
+ */
+function parseDurationMs(value, defaultHours = 24) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return defaultHours * 60 * 60 * 1000;
+
+  const match = text.match(/^(\d+(?:\.\d+)?)\s*([hmd]?)$/);
+  if (!match) return defaultHours * 60 * 60 * 1000;
+
+  const n = parseFloat(match[1]);
+  const unit = match[2] || 'h';
+  if (unit === 'd') return n * 24 * 60 * 60 * 1000;
+  if (unit === 'm') return n * 60 * 1000;
+  return n * 60 * 60 * 1000; // hours (default)
+}
+
+/**
+ * aioson agent:recover [targetDir] [--older-than=<duration>] [--dry-run]
+ *
+ * Detects and closes agent sessions that were abandoned (Claude Code closed before
+ * agent:done was called, or live:start session was never closed).
+ *
+ * Sources checked:
+ *   1. Session files in .aioson/.sessions/ with finished=false older than threshold.
+ *   2. agent_runs rows with status='running'/'queued' and started_at older than threshold
+ *      that have no corresponding live session file (orphaned DB records).
+ *
+ * --older-than  Duration threshold. Accepts: 24h (default), 8h, 30m, 7d.
+ * --dry-run     Report what would be recovered without making any changes.
+ * --json        Output JSON result.
+ */
+async function runAgentRecover({ args, options = {}, logger }) {
+  const targetDir = resolveTargetDir(args);
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
+  const olderThanMs = parseDurationMs(options['older-than'] || options.olderThan, 24);
+  const cutoffMs = Date.now() - olderThanMs;
+  const cutoffIso = new Date(cutoffMs).toISOString();
+  const now = new Date().toISOString();
+
+  const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
+
+  const recovered = [];
+  const skipped = [];
+
+  try {
+    // ── 1. Scan session files ─────────────────────────────────────────────────
+    const sessionsDir = path.join(runtimeDir, '.sessions');
+    let sessionFiles = [];
+    try {
+      const entries = await fs.readdir(sessionsDir);
+      sessionFiles = entries.filter((f) => f.endsWith('.json'));
+    } catch {
+      // .sessions dir may not exist — that's fine
+    }
+
+    for (const file of sessionFiles) {
+      const filePath = path.join(sessionsDir, file);
+      let session;
+      try {
+        session = JSON.parse(await fs.readFile(filePath, 'utf8'));
+      } catch {
+        continue;
+      }
+
+      if (session.finished) continue;
+
+      const startedAt = session.startedAt ? new Date(session.startedAt).getTime() : 0;
+      if (startedAt > cutoffMs) {
+        skipped.push({ source: 'session_file', file, reason: 'within_threshold', startedAt: session.startedAt });
+        continue;
+      }
+
+      const agentName = file.replace(/\.json$/, '');
+      const runKey = session.runKey || null;
+      const taskKey = session.taskKey || null;
+
+      if (!dryRun) {
+        // Mark run as abandoned
+        if (runKey) {
+          const runRow = db.prepare('SELECT run_key, status FROM agent_runs WHERE run_key = ?').get(runKey);
+          if (runRow && (runRow.status === 'running' || runRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE agent_runs
+              SET status = 'abandoned', summary = 'Recovered: session abandoned without close', updated_at = ?, finished_at = ?
+              WHERE run_key = ?
+            `).run(now, now, runKey);
+          }
+        }
+        // Mark task as abandoned
+        if (taskKey) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(taskKey);
+          if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE tasks
+              SET status = 'abandoned', updated_at = ?, finished_at = ?
+              WHERE task_key = ?
+            `).run(now, now, taskKey);
+          }
+        }
+        // Remove session file
+        try { await fs.unlink(filePath); } catch { /* noop */ }
+      }
+
+      recovered.push({ source: 'session_file', agent: agentName, runKey, taskKey, startedAt: session.startedAt });
+    }
+
+    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
+    const orphanedRuns = db.prepare(`
+      SELECT run_key, task_key, agent_name, started_at
+      FROM agent_runs
+      WHERE status IN ('running', 'queued')
+        AND source = 'direct'
+        AND started_at < ?
+    `).all(cutoffIso);
+
+    for (const run of orphanedRuns) {
+      // Skip if already recovered via session file
+      if (recovered.some((r) => r.runKey === run.run_key)) continue;
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE agent_runs
+          SET status = 'abandoned', summary = 'Recovered: orphaned run with no session file', updated_at = ?, finished_at = ?
+          WHERE run_key = ?
+        `).run(now, now, run.run_key);
+
+        if (run.task_key) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
+          if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
+            db.prepare(`
+              UPDATE tasks
+              SET status = 'abandoned', updated_at = ?, finished_at = ?
+              WHERE task_key = ?
+            `).run(now, now, run.task_key);
+          }
+        }
+      }
+
+      recovered.push({ source: 'orphaned_run', agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
+    }
+
+    // ── Output ────────────────────────────────────────────────────────────────
+    const olderThanLabel = options['older-than'] || options.olderThan || '24h';
+    if (recovered.length === 0) {
+      logger.log(`agent:recover — no abandoned sessions found older than ${olderThanLabel} (${dbPath})`);
+    } else {
+      const verb = dryRun ? '[dry-run] would recover' : 'recovered';
+      logger.log(`agent:recover — ${verb} ${recovered.length} abandoned session(s) older than ${olderThanLabel} (${dbPath})`);
+      for (const r of recovered) {
+        logger.log(`  ${r.agent}  started: ${r.startedAt || '?'}  run: ${r.runKey || '—'}  [${r.source}]`);
+      }
+    }
+    if (skipped.length > 0) {
+      logger.log(`  skipped ${skipped.length} session(s) within threshold.`);
+    }
+
+    return { ok: true, targetDir, dbPath, dryRun, cutoff: cutoffIso, recovered, skipped };
+  } finally {
+    db.close();
+  }
+}
+
+
+/**
+ * aioson runtime:prune [targetDir] --older-than=<days>
+ *
+ * Removes execution_events, agent_events, and completed agent_runs
+ * older than the specified number of days. Tasks are kept but their
+ * events are cleaned up.
+ */
+async function runRuntimePrune({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const days = parseInt(options['older-than'] || options.olderThan || '30', 10);
+
+  if (isNaN(days) || days < 1) {
+    logger.error('Usage: aioson runtime:prune --older-than=<days> (minimum 1)');
+    return { ok: false, error: 'Invalid --older-than value' };
+  }
+
+  const { db, dbPath } = await withRuntimeDb(targetDir, t);
+
+  try {
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+
+    const execEvents = db.prepare(
+      `DELETE FROM execution_events WHERE created_at < ?`
+    ).run(cutoff);
+
+    const agentEvents = db.prepare(
+      `DELETE FROM agent_events WHERE created_at < ?`
+    ).run(cutoff);
+
+    const runs = db.prepare(
+      `DELETE FROM agent_runs WHERE status IN ('completed', 'failed') AND finished_at < ?`
+    ).run(cutoff);
+
+    const tasks = db.prepare(
+      `DELETE FROM tasks WHERE status IN ('completed', 'failed') AND finished_at < ?`
+    ).run(cutoff);
+
+    const deliveryLogs = db.prepare(
+      `DELETE FROM delivery_log WHERE created_at < ?`
+    ).run(cutoff);
+
+    // Reclaim disk space
+    db.pragma('wal_checkpoint(TRUNCATE)');
+
+    const total = execEvents.changes + agentEvents.changes + runs.changes + tasks.changes + deliveryLogs.changes;
+
+    logger.log(`Pruned ${total} records older than ${days} days from ${dbPath}:`);
+    logger.log(`  execution_events: ${execEvents.changes}`);
+    logger.log(`  agent_events: ${agentEvents.changes}`);
+    logger.log(`  agent_runs: ${runs.changes}`);
+    logger.log(`  tasks: ${tasks.changes}`);
+    logger.log(`  delivery_log: ${deliveryLogs.changes}`);
+
+    return {
+      ok: true,
+      dbPath,
+      days,
+      cutoff,
+      deleted: {
+        execution_events: execEvents.changes,
+        agent_events: agentEvents.changes,
+        agent_runs: runs.changes,
+        tasks: tasks.changes,
+        delivery_log: deliveryLogs.changes,
+        total
+      }
+    };
+  } finally {
+    db.close();
+  }
+}
+
 module.exports = {
   runRuntimeInit,
   runRuntimeIngest,
@@ -944,5 +2006,16 @@ module.exports = {
   runRuntimeTaskFail,
   runRuntimeFail,
   runRuntimeStatus,
-  runRuntimeLog
+  runRuntimeLog,
+  runAgentDone,
+  runAgentRecover,
+  runRuntimeSessionStart,
+  runRuntimeSessionLog,
+  runRuntimeSessionFinish,
+  runRuntimeSessionStatus,
+  runDeliver,
+  runOutputStrategyExport,
+  runOutputStrategyImport,
+  runDevlogSync,
+  runRuntimePrune
 };