@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/commands/runner-run.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const path = require('node:path');
+const { launchCLI, detectCLI } = require('../runner/cli-launcher');
+const { runWithCascade, parseCascadeChain } = require('../runner/cascade');
+const { openRuntimeDb, startRun, updateRun, createRunKey } = require('../runtime-store');
+
+/**
+ * aioson runner:run — executa uma única task headless usando o CLI de AI ativo.
+ *
+ * Usage:
+ *   aioson runner:run . --task="Fix the auth modal" --agent=dev
+ *   aioson runner:run . --task="..." --agent=qa --timeout=300
+ *   aioson runner:run . --task="..." --agent=dev --cascade=haiku,sonnet
+ *   aioson runner:run . --task="..." --dry-run
+ */
+async function runRunnerRun({ args, options = {}, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const { task, agent = 'dev', dryRun, cascade: cascadeStr } = options;
+  const timeout = options.timeout ? Number(options.timeout) * 1000 : 120000;
+
+  if (!task) {
+    logger.error('--task is required. Example: aioson runner:run . --task="Fix the login modal"');
+    return { ok: false };
+  }
+
+  const agentFile = path.join(projectDir, '.aioson', 'agents', `${agent}.md`);
+  const prompt = buildRunnerPrompt(task, agentFile);
+
+  if (dryRun) {
+    let cli;
+    try { cli = await detectCLI(); } catch { cli = 'claude'; }
+    logger.log(`[dry-run] Would run: ${cli} -p "${prompt.slice(0, 120)}..."`);
+    logger.log(`[dry-run] Agent: @${agent} | Timeout: ${timeout / 1000}s`);
+    if (cascadeStr) logger.log(`[dry-run] Cascade: ${cascadeStr}`);
+    return { ok: true, dryRun: true };
+  }
+
+  logger.log(`[runner] Task: ${task}`);
+  logger.log(`[runner] Agent: @${agent} | Timeout: ${timeout / 1000}s`);
+  if (cascadeStr) logger.log(`[runner] Cascade: ${cascadeStr}`);
+
+  const start = Date.now();
+
+  // Abre DB para registrar evento (melhor esforço — não bloqueia se não existir)
+  let db = null;
+  let runKey = null;
+  try {
+    const handle = await openRuntimeDb(projectDir, {});
+    if (handle) {
+      db = handle.db;
+      runKey = createRunKey(agent);
+      startRun(db, {
+        runKey,
+        agentName: agent,
+        agentKind: 'runner',
+        source: 'runner',
+        title: task.slice(0, 80),
+        status: 'running',
+        message: `Runner task started: ${task.slice(0, 80)}`
+      });
+    }
+  } catch { /* dashboard logging is best-effort */ }
+
+  let result;
+  const cascadeChain = parseCascadeChain(cascadeStr);
+
+  if (cascadeChain.length > 0) {
+    const cascadeResult = await runWithCascade(projectDir, prompt, cascadeChain, {
+      timeout,
+      onProgress: ({ model, attempt, maxAttempts, status, reason }) => {
+        if (status === 'running') {
+          logger.log(`[cascade] ${model} attempt ${attempt}/${maxAttempts}...`);
+        } else if (status === 'gate_failed') {
+          logger.log(`[cascade] ${model} attempt ${attempt} — gate failed${reason ? ': ' + reason : ''}, escalating...`);
+        } else if (status === 'cli_failed') {
+          logger.log(`[cascade] ${model} attempt ${attempt} — CLI failed, retrying...`);
+        }
+      }
+    });
+    if (cascadeResult.ok) {
+      result = cascadeResult.result;
+      logger.log(`[runner] Completed via ${cascadeResult.modelUsed} (attempt ${cascadeResult.attempts})`);
+    } else {
+      result = { ok: false, output: '', completionMarker: false };
+      logger.error(`[runner] ${cascadeResult.error}`);
+    }
+  } else {
+    result = await launchCLI(projectDir, prompt, {
+      timeout,
+      onData: (chunk) => process.stdout.write(chunk)
+    });
+  }
+
+  const elapsed = Math.round((Date.now() - start) / 1000);
+  const status = result.ok ? 'completed' : 'failed';
+
+  logger.log(`\n[runner] Task ${status} in ${elapsed}s`);
+  if (result.completionMarker) logger.log('[runner] TASK_COMPLETE marker detected');
+
+  // Atualiza run no dashboard
+  if (db && runKey) {
+    try {
+      updateRun(db, {
+        runKey,
+        status,
+        message: `Runner task ${status}: ${task.slice(0, 80)}`,
+        payload: { task, agent, elapsed, ok: result.ok, completionMarker: result.completionMarker }
+      });
+    } catch { /* best-effort */ }
+    try { db.close(); } catch { /* noop */ }
+  }
+
+  return { ok: result.ok, output: result.output, elapsed, completionMarker: result.completionMarker };
+}
+
+function buildRunnerPrompt(task, agentFile) {
+  return [
+    'You are operating in autonomous headless mode. Complete the following task independently.',
+    `Agent role: read ${agentFile} for your operating instructions.`,
+    '',
+    `Task: ${task}`,
+    '',
+    'When the task is complete, write TASK_COMPLETE on a new line as the final output.',
+    'If you cannot complete the task, write TASK_FAILED: [reason].'
+  ].join('\n');
+}
+
+module.exports = { runRunnerRun };

package/src/commands/runtime.js

@@ -1179,6 +1179,11 @@ async function runAgentDone({ args, options = {}, logger, t }) {
   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 verdict = options.verdict ? String(options.verdict).trim().toUpperCase() : null;
+  const planStepId = options['plan-step'] ? String(options['plan-step']).trim() : null;
+  const artifactPaths = options.artifacts
+    ? String(options.artifacts).split(',').map((p) => p.trim()).filter(Boolean)
+    : [];
 
   const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
 
@@ -1194,9 +1199,24 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         eventType: 'agent_done',
         phase: 'live',
         status: 'running',
-        message: summary
+        message: summary,
+        verdict,
+        planStepId
       });
 
+      if (artifactPaths.length > 0) {
+        for (const filePath of artifactPaths) {
+          try {
+            attachArtifact(db, {
+              runKey: session.runKey,
+              agentName: normalizedAgent,
+              kind: 'output',
+              filePath
+            });
+          } catch { /* non-fatal */ }
+        }
+      }
+
       if (!options.json) {
         logger.log(`agent:done — ${normalizedAgent} | live session active, event logged | run: ${session.runKey} (${dbPath})`);
       }
@@ -1219,6 +1239,32 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       summary
     });
 
+    if (verdict || planStepId) {
+      appendRunEvent(db, {
+        runKey,
+        eventType: 'agent_done',
+        phase: 'direct',
+        status: 'completed',
+        message: summary,
+        verdict,
+        planStepId
+      });
+    }
+
+    if (artifactPaths.length > 0) {
+      for (const filePath of artifactPaths) {
+        try {
+          attachArtifact(db, {
+            runKey,
+            taskKey,
+            agentName: normalizedAgent,
+            kind: 'output',
+            filePath
+          });
+        } catch { /* non-fatal */ }
+      }
+    }
+
     if (!options.json) {
       logger.log(`agent:done — ${normalizedAgent} | task: ${taskKey} | run: ${runKey} (${dbPath})`);
     }

package/src/commands/self-implement-loop.js

@@ -0,0 +1,256 @@
+'use strict';
+
+/**
+ * aioson self:loop — Autonomous implement + verify loop
+ *
+ * Runs an agent task, verifies with verify-gate in a fresh context,
+ * and retries with feedback injection on failure.
+ *
+ * Usage:
+ *   aioson self:loop . --agent=dev --task="implement stripe webhook handler" --max-iterations=3
+ *   aioson self:loop . --agent=dev --task="..." --verification-criteria="all tests pass"
+ *   aioson self:loop . --agent=dev --task="..." --spec=briefs/phase-1.md --artifact=src/
+ *
+ * Integrates with:
+ *   - verify-gate.js for tiered verification (tiers 1–4)
+ *   - intra-bus.js for recording attempts
+ *   - state-manager.js for recording final result
+ */
+
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const fs = require('node:fs/promises');
+
+const bus = require('../squad/intra-bus');
+const stateManager = require('../squad/state-manager');
+
+// ─── Agent execution ─────────────────────────────────────────────────────────
+
+/**
+ * Execute an agent task via the aioson CLI.
+ * Returns { ok, output, error }.
+ */
+function executeAgent(projectDir, agent, task, feedbackContext, timeoutMs) {
+  const prompt = feedbackContext
+    ? `${task}\n\n---\nPrevious attempt feedback:\n${feedbackContext}`
+    : task;
+
+  try {
+    const output = execSync(
+      `aioson agent:prompt ${agent} . --tool=claude`,
+      {
+        cwd: projectDir,
+        input: prompt,
+        timeout: timeoutMs,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024 * 5,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }
+    );
+    return { ok: true, output: output.trim() };
+  } catch (err) {
+    return { ok: false, output: '', error: err.message.slice(0, 500) };
+  }
+}
+
+/**
+ * Run verify-gate on the result.
+ * Returns { ok, verdict, issues }.
+ */
+async function runVerification(projectDir, spec, artifact, criteria) {
+  if (!spec || !artifact) {
+    // Fallback: criteria-only verification
+    return criteriaOnlyVerify(projectDir, artifact, criteria);
+  }
+
+  try {
+    const output = execSync(
+      `aioson verify:gate . --spec="${spec}" --artifact="${artifact}" --json`,
+      {
+        cwd: projectDir,
+        timeout: 30_000,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024
+      }
+    );
+    const result = JSON.parse(output);
+    return {
+      ok: result.verdict === 'PASS' || result.verdict === 'PASS_WITH_NOTES',
+      verdict: result.verdict,
+      issues: result.issues || []
+    };
+  } catch (err) {
+    return { ok: false, verdict: 'BLOCKED', issues: [{ message: err.message.slice(0, 200) }] };
+  }
+}
+
+/**
+ * Simple criteria-based verification when no spec/artifact is given.
+ * Checks if verification criteria strings are present in the output directory.
+ */
+async function criteriaOnlyVerify(projectDir, artifactPath, criteria) {
+  if (!criteria) {
+    return { ok: true, verdict: 'PASS', issues: [] };
+  }
+
+  const issues = [];
+  const criteriaList = criteria.split(',').map((c) => c.trim());
+
+  for (const criterion of criteriaList) {
+    if (/test/i.test(criterion)) {
+      // Check if tests pass
+      try {
+        execSync('npm test --if-present 2>&1', {
+          cwd: projectDir,
+          timeout: 60_000,
+          encoding: 'utf8'
+        });
+      } catch {
+        issues.push({ message: `Test criterion failed: "${criterion}"` });
+      }
+    }
+  }
+
+  return {
+    ok: issues.length === 0,
+    verdict: issues.length === 0 ? 'PASS' : 'FAIL_WITH_ISSUES',
+    issues
+  };
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Run the self-implement loop.
+ *
+ * @param {object} params
+ * @returns {Promise<object>}  — { ok, iterations, verdict, feedback[] }
+ */
+async function runSelfLoop({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agent = String(options.agent || options.a || 'dev').trim();
+  const task = String(options.task || options.t || '').trim();
+  const maxIterations = Math.min(Math.max(Number(options['max-iterations'] || 3), 1), 5);
+  const spec = options.spec ? String(options.spec).trim() : null;
+  const artifact = options.artifact ? String(options.artifact).trim() : null;
+  const criteria = options['verification-criteria'] || options.criteria || '';
+  const squad = options.squad ? String(options.squad).trim() : null;
+  const timeoutMs = (Number(options.timeout) || 300) * 1000;
+
+  if (!task) {
+    logger.error('Error: --task is required');
+    return { ok: false, error: 'missing_task' };
+  }
+
+  const sessionId = randomUUID();
+  const feedbackHistory = [];
+
+  logger.log(`Self-implement loop: @${agent} — "${task.slice(0, 60)}${task.length > 60 ? '...' : ''}"`);
+  logger.log(`Max iterations: ${maxIterations}`);
+  if (spec) logger.log(`Spec: ${spec}`);
+  if (artifact) logger.log(`Artifact: ${artifact}`);
+  logger.log('');
+
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    logger.log(`── Iteration ${iteration}/${maxIterations} ──────────────────────────`);
+
+    // Step 1: Execute agent
+    const feedbackContext = feedbackHistory.length > 0
+      ? feedbackHistory.map((f) => `[Iteration ${f.iteration}] ${f.verdict}: ${f.issues.map((i) => i.message).join('; ')}`).join('\n')
+      : null;
+
+    logger.log(`  Running @${agent}...`);
+    const agentResult = executeAgent(targetDir, agent, task, feedbackContext, timeoutMs);
+
+    if (!agentResult.ok) {
+      logger.log(`  ✗ Agent execution failed: ${agentResult.error?.slice(0, 100)}`);
+      // Record on bus if squad context
+      if (squad) {
+        await bus.post(targetDir, squad, sessionId, {
+          from: 'self-loop',
+          type: 'status',
+          content: `Iteration ${iteration} — agent failed: ${agentResult.error?.slice(0, 200)}`
+        }).catch(() => {});
+      }
+      continue;
+    }
+
+    // Step 2: Verify (fresh context)
+    logger.log('  Verifying...');
+    const verifyResult = await runVerification(targetDir, spec, artifact, criteria);
+
+    // Record on bus
+    if (squad) {
+      await bus.post(targetDir, squad, sessionId, {
+        from: 'self-loop',
+        type: verifyResult.ok ? 'result' : 'gap_closure_attempt',
+        content: `Iteration ${iteration}: ${verifyResult.verdict}`,
+        metadata: {
+          iteration,
+          verdict: verifyResult.verdict,
+          issues_count: verifyResult.issues.length
+        }
+      }).catch(() => {});
+    }
+
+    // Step 3: Check result
+    if (verifyResult.ok) {
+      logger.log(`  ✓ PASS${iteration > 1 ? ` (after ${iteration} iteration${iteration > 1 ? 's' : ''})` : ''}`);
+
+      // Record success in state
+      if (squad) {
+        await stateManager.updateState(targetDir, squad, {
+          addDecision: [`self-loop: "${task.slice(0, 50)}" completed in ${iteration} iteration(s)`]
+        }).catch(() => {});
+      }
+
+      if (options.json) {
+        return { ok: true, iterations: iteration, verdict: verifyResult.verdict, feedback: feedbackHistory };
+      }
+
+      return { ok: true, iterations: iteration, verdict: verifyResult.verdict };
+    }
+
+    // Step 4: Collect feedback for next iteration
+    logger.log(`  ✗ ${verifyResult.verdict} — ${verifyResult.issues.length} issue(s)`);
+    for (const issue of verifyResult.issues.slice(0, 5)) {
+      logger.log(`    - ${issue.message}`);
+    }
+
+    feedbackHistory.push({
+      iteration,
+      verdict: verifyResult.verdict,
+      issues: verifyResult.issues
+    });
+  }
+
+  // Step 5: Exhausted — escalate
+  logger.log('');
+  logger.log(`✗ Max iterations (${maxIterations}) exhausted — escalating to user`);
+
+  if (squad) {
+    await bus.post(targetDir, squad, sessionId, {
+      from: 'self-loop',
+      type: 'block',
+      content: `Self-implement loop exhausted ${maxIterations} iterations for: "${task.slice(0, 100)}"`,
+      metadata: { exhausted: true, iterations: maxIterations }
+    }).catch(() => {});
+
+    await stateManager.updateState(targetDir, squad, {
+      addBlocker: [`self-loop exhausted: "${task.slice(0, 50)}" (${maxIterations} iterations)`]
+    }).catch(() => {});
+  }
+
+  const result = {
+    ok: false,
+    iterations: maxIterations,
+    verdict: 'EXHAUSTED',
+    feedback: feedbackHistory
+  };
+
+  if (options.json) return result;
+  return result;
+}
+
+module.exports = { runSelfLoop };

package/src/commands/session-guard.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * aioson session:guard [projectDir] --agent=<name> --tool=<tool>
+ *
+ * Background supervisor that keeps a live session alive.
+ * - If no live session exists: auto-starts one (no-launch mode)
+ * - Polls every 30s to verify the session is still open
+ * - Detects inactivity (no events for --idle-minutes, default: 60) and closes gracefully
+ * - Works alongside hooks:emit — guard handles session lifecycle, hooks handle events
+ *
+ * Run in background:
+ *   aioson session:guard . --agent=dev --tool=claude &
+ *
+ * Or as a foreground check (--once):
+ *   aioson session:guard . --agent=dev --tool=claude --once
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const {
+  openRuntimeDb,
+  resolveRuntimePaths,
+  readAgentSession,
+  writeAgentSession,
+  startTask,
+  startRun,
+  updateRun,
+  updateTask,
+  appendRunEvent
+} = require('../runtime-store');
+
+const POLL_INTERVAL_MS = 30_000;
+const DEFAULT_IDLE_MINUTES = 60;
+
+function nowIso() { return new Date().toISOString(); }
+function log(msg) { process.stderr.write(`[session:guard] ${msg}\n`); }
+
+async function getLastEventTime(runtimeDir, sessionKey) {
+  const eventsPath = path.join(runtimeDir, 'live', sessionKey, 'events.ndjson');
+  try {
+    const content = await fs.readFile(eventsPath, 'utf8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    const last = JSON.parse(lines[lines.length - 1]);
+    return last.ts ? new Date(last.ts) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function startLiveSession(targetDir, runtimeDir, agentName, tool) {
+  const now = nowIso();
+  const sessionKey = `guard-${agentName}-${Date.now()}`;
+  const title = `[guard] ${agentName} via ${tool}`;
+
+  const { db } = await openRuntimeDb(targetDir);
+  try {
+    const taskKey = startTask(db, {
+      sessionKey,
+      title,
+      status: 'running',
+      createdBy: agentName,
+      taskKind: 'live_session',
+      metaJson: { tool_session: tool, path: targetDir, guarded: true }
+    });
+
+    const runKey = startRun(db, {
+      taskKey,
+      agentName,
+      agentKind: 'official',
+      sessionKey,
+      source: 'live',
+      title,
+      eventType: 'session_started',
+      phase: 'live',
+      message: `Session auto-started by session:guard (${tool})`,
+      payload: { tool_session: tool, path: targetDir, guarded: true }
+    });
+
+    await writeAgentSession(runtimeDir, agentName, {
+      runKey, taskKey, sessionKey,
+      startedAt: now, finished: false, source: 'live'
+    });
+
+    // Create state.json for dashboard
+    const stateDir = path.join(runtimeDir, 'live', sessionKey);
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, 'state.json'), JSON.stringify({
+      session_key: sessionKey, run_key: runKey, task_key: taskKey,
+      agent_name: agentName, tool_session: tool,
+      status: 'running', started_at: now, updated_at: now, guarded: true,
+      last_events: [{ ts: now, type: 'session_started', summary: `Auto-started by session:guard (${tool})` }]
+    }, null, 2), 'utf8');
+
+    log(`Session started: ${sessionKey} (run: ${runKey})`);
+    return { runKey, taskKey, sessionKey };
+  } finally {
+    db.close();
+  }
+}
+
+async function closeSession(targetDir, runtimeDir, agentName, runKey, taskKey, reason) {
+  const now = nowIso();
+  const { db } = await openRuntimeDb(targetDir, { mustExist: true });
+  try {
+    appendRunEvent(db, {
+      runKey, eventType: 'session_ended', phase: 'live',
+      status: 'completed', message: `Session closed by session:guard: ${reason}`,
+      createdAt: now
+    });
+    updateRun(db, runKey, { status: 'completed', summary: reason, finishedAt: now });
+    if (taskKey) updateTask(db, taskKey, { status: 'completed', finishedAt: now });
+
+    // Update state.json
+    const { db: _, ...rest } = await readAgentSession(runtimeDir, agentName).catch(() => ({}));
+    const sessionKey = rest?.sessionKey;
+    if (sessionKey) {
+      const statePath = path.join(runtimeDir, 'live', sessionKey, 'state.json');
+      try {
+        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        state.status = 'closed';
+        state.updated_at = now;
+        await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8');
+      } catch { /* non-fatal */ }
+    }
+
+    // Clear session file
+    const sessionFile = path.join(runtimeDir, '.sessions', `${agentName}.json`);
+    try { await fs.unlink(sessionFile); } catch { /* already gone */ }
+
+    log(`Session closed: ${runKey} (${reason})`);
+  } finally {
+    db.close();
+  }
+}
+
+async function tick(targetDir, runtimeDir, agentName, tool, idleMs, state) {
+  const session = await readAgentSession(runtimeDir, agentName);
+
+  if (!session || session.finished) {
+    // No session — start one
+    const created = await startLiveSession(targetDir, runtimeDir, agentName, tool);
+    state.runKey = created.runKey;
+    state.taskKey = created.taskKey;
+    state.sessionKey = created.sessionKey;
+    state.startedAt = Date.now();
+    return;
+  }
+
+  // Session exists — check for idle timeout
+  const sessionKey = session.sessionKey;
+  const lastEvent = await getLastEventTime(runtimeDir, sessionKey);
+  const now = Date.now();
+  const lastActivity = lastEvent ? lastEvent.getTime() : state.startedAt;
+  const idleFor = now - lastActivity;
+
+  if (idleFor > idleMs) {
+    const idleMin = Math.round(idleFor / 60000);
+    log(`Idle for ${idleMin}m — closing session`);
+    await closeSession(targetDir, runtimeDir, agentName, session.runKey, session.taskKey,
+      `Idle for ${idleMin} minutes`);
+    state.runKey = null;
+    state.taskKey = null;
+    state.sessionKey = null;
+  }
+}
+
+async function runSessionGuard({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  const tool = options.tool ? String(options.tool).trim() : 'claude';
+  const once = options.once || options['once'] || false;
+  const idleMinutes = Number(options['idle-minutes'] || options.idleMinutes || DEFAULT_IDLE_MINUTES);
+  const idleMs = idleMinutes * 60 * 1000;
+  const intervalMs = Number(options.interval || POLL_INTERVAL_MS);
+
+  const { runtimeDir } = resolveRuntimePaths(targetDir);
+  const state = { runKey: null, taskKey: null, sessionKey: null, startedAt: Date.now() };
+
+  if (!options.json) {
+    logger.log(`[session:guard] Watching: ${targetDir}`);
+    logger.log(`[session:guard] Agent: @${agentName} | Tool: ${tool} | Idle timeout: ${idleMinutes}m`);
+    logger.log(`[session:guard] Press Ctrl+C to stop.`);
+  }
+
+  await tick(targetDir, runtimeDir, agentName, tool, idleMs, state);
+
+  if (once) {
+    return { ok: true, runKey: state.runKey, sessionKey: state.sessionKey };
+  }
+
+  return new Promise((resolve) => {
+    const timer = setInterval(async () => {
+      try {
+        await tick(targetDir, runtimeDir, agentName, tool, idleMs, state);
+      } catch (err) {
+        log(`Error: ${err.message}`);
+      }
+    }, intervalMs);
+
+    const shutdown = async () => {
+      clearInterval(timer);
+      if (state.runKey) {
+        try {
+          await closeSession(targetDir, runtimeDir, agentName, state.runKey, state.taskKey, 'session:guard stopped');
+        } catch { /* best-effort */ }
+      }
+      if (!options.json) logger.log('[session:guard] Stopped.');
+      resolve({ ok: true });
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+}
+
+module.exports = { runSessionGuard };