@openparachute/agent 0.1.0

package/src/host-sweep.ts

@@ -0,0 +1,287 @@
+/**
+ * Host sweep — periodic maintenance of all session DBs.
+ *
+ * Two-DB architecture:
+ *   - Reads processing_ack + container_state from outbound.db
+ *   - Writes to inbound.db (host-owned) for status updates + recurrence
+ *   - Uses heartbeat file mtime for liveness (never polls DB for it)
+ *   - Never writes to outbound.db — preserves single-writer-per-file invariant
+ *
+ * Stuck / idle detection (replaces the old IDLE_TIMEOUT setTimeout + 10-min
+ * heartbeat threshold):
+ *
+ *   If the container isn't running and there are 'processing' rows left over
+ *   (e.g. it crashed mid-turn) → reset them to pending with backoff +
+ *   tries++. Existing retry machinery does the rest.
+ *
+ *   If the container IS running:
+ *     1. Absolute ceiling: heartbeat age > max(30 min, current_bash_timeout)
+ *        → kill. Covers the "alive but silent for 30 min" case. Extended
+ *        only while Bash is declared as running longer, honouring the
+ *        user's own timeout directive. Kill then resets processing rows.
+ *
+ *     2. Message-scoped stuck: for each 'processing' row, tolerance =
+ *        max(60s, current_bash_timeout_ms_if_Bash_running). If
+ *        (claim_age > tolerance) AND (heartbeat_mtime <= status_changed)
+ *        → kill + reset this message + tries++. Semantics: "container
+ *        claimed a message and went quiet past tolerance since the claim."
+ */
+import type { Database } from './db/connection.js';
+import fs from 'fs';
+
+import { getActiveSessions } from './db/sessions.js';
+import { getAgentGroup } from './db/agent-groups.js';
+import {
+  countDueMessages,
+  getContainerState,
+  getMessageForRetry,
+  getProcessingClaims,
+  markMessageFailed,
+  retryWithBackoff,
+  syncProcessingAcks,
+  type ContainerState,
+} from './db/session-db.js';
+import { log } from './log.js';
+import { sweepExpiredStates } from './oauth/state-store.js';
+import { openInboundDb, openOutboundDb, inboundDbPath, heartbeatPath } from './session-manager.js';
+import { isContainerRunning, killContainer, wakeContainer } from './container-runner.js';
+import type { Session } from './types.js';
+
+const SWEEP_INTERVAL_MS = 60_000;
+// Absolute idle ceiling for a running container. If the heartbeat file hasn't
+// been touched in this long, the container is either stuck or doing genuinely
+// nothing — kill and restart on the next inbound.
+export const ABSOLUTE_CEILING_MS = 30 * 60 * 1000;
+// Stuck tolerance window applied per 'processing' claim — "did we see any
+// signs of life since this message was claimed?"
+export const CLAIM_STUCK_MS = 60 * 1000;
+const MAX_TRIES = 5;
+const BACKOFF_BASE_MS = 5000;
+
+export type StuckDecision =
+  | { action: 'ok' }
+  | { action: 'kill-ceiling'; heartbeatAgeMs: number; ceilingMs: number }
+  | { action: 'kill-claim'; messageId: string; claimAgeMs: number; toleranceMs: number };
+
+/**
+ * Pure decision for whether a running container should be killed this sweep
+ * tick. Inputs are all deterministic; filesystem + DB reads happen in the
+ * caller.
+ */
+export function decideStuckAction(args: {
+  now: number;
+  heartbeatMtimeMs: number; // 0 when heartbeat file absent
+  containerState: ContainerState | null;
+  claims: Array<{ message_id: string; status_changed: string }>;
+}): StuckDecision {
+  const { now, heartbeatMtimeMs, containerState, claims } = args;
+  const declaredBashMs = bashTimeoutMs(containerState);
+
+  // Ceiling check only applies when we have an actual heartbeat timestamp.
+  // A freshly-spawned container hasn't had any SDK activity yet so no
+  // heartbeat file exists — if we treated that as infinitely stale we'd
+  // kill every container within seconds of spawn. Genuinely-dead containers
+  // that never wrote a heartbeat are caught by the separate "container
+  // process not running" cleanup path, not here. If a fresh container is
+  // hanging at the gate (claimed a message but never did anything) the
+  // claim-stuck check below handles it.
+  if (heartbeatMtimeMs !== 0) {
+    const heartbeatAge = now - heartbeatMtimeMs;
+    const ceiling = Math.max(ABSOLUTE_CEILING_MS, declaredBashMs ?? 0);
+    if (heartbeatAge > ceiling) {
+      return { action: 'kill-ceiling', heartbeatAgeMs: heartbeatAge, ceilingMs: ceiling };
+    }
+  }
+
+  const tolerance = Math.max(CLAIM_STUCK_MS, declaredBashMs ?? 0);
+  for (const claim of claims) {
+    const claimedAt = Date.parse(claim.status_changed);
+    if (Number.isNaN(claimedAt)) continue;
+    const claimAge = now - claimedAt;
+    if (claimAge <= tolerance) continue;
+    if (heartbeatMtimeMs > claimedAt) continue;
+    return { action: 'kill-claim', messageId: claim.message_id, claimAgeMs: claimAge, toleranceMs: tolerance };
+  }
+
+  return { action: 'ok' };
+}
+
+let running = false;
+
+export function startHostSweep(): void {
+  if (running) return;
+  running = true;
+  sweep();
+}
+
+export function stopHostSweep(): void {
+  running = false;
+}
+
+async function sweep(): Promise<void> {
+  if (!running) return;
+
+  try {
+    const sessions = getActiveSessions();
+    for (const session of sessions) {
+      await sweepSession(session);
+    }
+  } catch (err) {
+    log.error('Host sweep error', { err });
+  }
+
+  // Global (non-per-session) maintenance: drop expired OAuth CSRF state rows.
+  // DB-backed state store grows by ~1 row per failed authorize attempt
+  // otherwise.
+  try {
+    const removed = sweepExpiredStates();
+    if (removed > 0) log.info('Swept expired oauth states', { removed });
+  } catch (err) {
+    log.warn('sweepExpiredStates failed', { err: err instanceof Error ? err.message : String(err) });
+  }
+
+  setTimeout(sweep, SWEEP_INTERVAL_MS);
+}
+
+async function sweepSession(session: Session): Promise<void> {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) return;
+
+  const inPath = inboundDbPath(agentGroup.id, session.id);
+  if (!fs.existsSync(inPath)) return;
+
+  let inDb: Database;
+  let outDb: Database | null = null;
+  try {
+    inDb = openInboundDb(agentGroup.id, session.id);
+  } catch {
+    return;
+  }
+
+  try {
+    outDb = openOutboundDb(agentGroup.id, session.id);
+  } catch {
+    // outbound.db might not exist yet (container hasn't started)
+  }
+
+  try {
+    // 1. Sync processing_ack → messages_in status
+    if (outDb) {
+      syncProcessingAcks(inDb, outDb);
+    }
+
+    // 2. Wake a container if work is due and nothing is running. Ordered
+    // before the crashed-container cleanup so a fresh container gets a chance
+    // to clean its own orphan processing_ack rows on startup (see
+    // container/agent-runner/src/db/connection.ts). Otherwise the reset path
+    // would keep bumping process_after into the future, dueCount would stay 0,
+    // and the wake would never fire.
+    const dueCount = countDueMessages(inDb);
+    if (dueCount > 0 && !isContainerRunning(session.id)) {
+      log.info('Waking container for due messages', { sessionId: session.id, count: dueCount });
+      await wakeContainer(session);
+    }
+
+    const alive = isContainerRunning(session.id);
+
+    // 3. Running-container SLA: absolute ceiling + per-claim stuck rules.
+    if (alive && outDb) {
+      enforceRunningContainerSla(inDb, outDb, session, agentGroup.id);
+    }
+
+    // 4. Crashed-container cleanup: processing rows left behind get retried.
+    // Only fires when wake in step 2 didn't pick up the work (no due messages,
+    // or wake failed). resetStuckProcessingRows itself is idempotent — it
+    // skips messages already scheduled for a future retry.
+    if (!alive && outDb) {
+      resetStuckProcessingRows(inDb, outDb, session, 'container not running');
+    }
+
+    // 5. Recurrence fanout for completed recurring tasks.
+    // MODULE-HOOK:scheduling-recurrence:start
+    const { handleRecurrence } = await import('./modules/scheduling/recurrence.js');
+    await handleRecurrence(inDb, session);
+    // MODULE-HOOK:scheduling-recurrence:end
+  } finally {
+    inDb.close();
+    outDb?.close();
+  }
+}
+
+function heartbeatMtimeMs(agentGroupId: string, sessionId: string): number {
+  const hbPath = heartbeatPath(agentGroupId, sessionId);
+  try {
+    return fs.statSync(hbPath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function bashTimeoutMs(state: ContainerState | null): number | null {
+  if (!state || state.current_tool !== 'Bash') return null;
+  return typeof state.tool_declared_timeout_ms === 'number' ? state.tool_declared_timeout_ms : null;
+}
+
+function enforceRunningContainerSla(inDb: Database, outDb: Database, session: Session, agentGroupId: string): void {
+  const decision = decideStuckAction({
+    now: Date.now(),
+    heartbeatMtimeMs: heartbeatMtimeMs(agentGroupId, session.id),
+    containerState: getContainerState(outDb),
+    claims: getProcessingClaims(outDb),
+  });
+
+  if (decision.action === 'ok') return;
+
+  if (decision.action === 'kill-ceiling') {
+    log.warn('Killing container past absolute ceiling', {
+      sessionId: session.id,
+      heartbeatAgeMs: decision.heartbeatAgeMs,
+      ceilingMs: decision.ceilingMs,
+    });
+    killContainer(session.id, 'absolute-ceiling');
+    resetStuckProcessingRows(inDb, outDb, session, 'absolute-ceiling');
+    return;
+  }
+
+  log.warn('Killing container — message claimed then silent', {
+    sessionId: session.id,
+    messageId: decision.messageId,
+    claimAgeMs: decision.claimAgeMs,
+    toleranceMs: decision.toleranceMs,
+  });
+  killContainer(session.id, 'claim-stuck');
+  resetStuckProcessingRows(inDb, outDb, session, 'claim-stuck');
+}
+
+function resetStuckProcessingRows(inDb: Database, outDb: Database, session: Session, reason: string): void {
+  const claims = getProcessingClaims(outDb);
+  const now = Date.now();
+  for (const { message_id } of claims) {
+    const msg = getMessageForRetry(inDb, message_id, 'pending');
+    if (!msg) continue;
+
+    // Already rescheduled for a future retry — don't bump tries again. The
+    // wake path (sweep step 2) will fire when process_after elapses and a
+    // fresh container will clean the orphan claim on startup.
+    if (msg.processAfter && Date.parse(msg.processAfter) > now) continue;
+
+    if (msg.tries >= MAX_TRIES) {
+      markMessageFailed(inDb, msg.id);
+      log.warn('Message marked as failed after max retries', {
+        messageId: msg.id,
+        sessionId: session.id,
+        reason,
+      });
+    } else {
+      const backoffMs = BACKOFF_BASE_MS * Math.pow(2, msg.tries);
+      const backoffSec = Math.floor(backoffMs / 1000);
+      retryWithBackoff(inDb, msg.id, backoffSec);
+      log.info('Reset stale message with backoff', {
+        messageId: msg.id,
+        tries: msg.tries,
+        backoffMs,
+        reason,
+      });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,227 @@
+/**
+ * parachute-agent — main entry point.
+ *
+ * Thin orchestrator: init DB, run migrations, start channel adapters,
+ * start delivery polls, start sweep, handle shutdown.
+ */
+import http from 'node:http';
+
+import { CENTRAL_DB_PATH } from './config.js';
+import { migrateGroupsToClaudeLocal } from './claude-md-compose.js';
+import { initDb, migrateCentralDbLocation, migrateMasterKeyLocation } from './db/connection.js';
+import { runMigrations } from './db/migrations/index.js';
+import { ensureContainerRuntimeRunning, cleanupOrphans } from './container-runtime.js';
+import { startActiveDeliveryPoll, startSweepDeliveryPoll, setDeliveryAdapter, stopDeliveryPolls } from './delivery.js';
+import { startHostSweep, stopHostSweep } from './host-sweep.js';
+import { routeInbound } from './router.js';
+import { migrateSessionsDir } from './session-manager.js';
+import { startWebServer } from './web/server.js';
+import { log, migrateLegacyLogFilenames } from './log.js';
+import { migrateLegacyAllowlistDir } from './modules/mount-security/index.js';
+import { runStartupBootstrap } from './startup-bootstrap.js';
+
+// Response + shutdown registries live in response-registry.ts to break the
+// circular import cycle: src/index.ts imports src/modules/index.js for side
+// effects, and the modules call registerResponseHandler/onShutdown at top
+// level — which would hit a TDZ error if the arrays lived here. Re-exported
+// here so existing callers see the same surface.
+import {
+  registerResponseHandler,
+  getResponseHandlers,
+  onShutdown,
+  getShutdownCallbacks,
+  type ResponsePayload,
+  type ResponseHandler,
+} from './response-registry.js';
+export { registerResponseHandler, onShutdown };
+export type { ResponsePayload, ResponseHandler };
+
+let webServer: http.Server | null = null;
+
+async function dispatchResponse(payload: ResponsePayload): Promise<void> {
+  for (const handler of getResponseHandlers()) {
+    try {
+      const claimed = await handler(payload);
+      if (claimed) return;
+    } catch (err) {
+      log.error('Response handler threw', { questionId: payload.questionId, err });
+    }
+  }
+  log.warn('Unclaimed response', { questionId: payload.questionId, value: payload.value });
+}
+
+// Channel barrel — each enabled channel self-registers on import.
+// Channel skills uncomment lines in channels/index.ts to enable them.
+import './channels/index.js';
+
+// Modules barrel — default modules (typing, mount-security) ship here; skills
+// append registry-based modules. Imported for side effects (registrations).
+import './modules/index.js';
+
+import type { ChannelAdapter, ChannelSetup } from './channels/adapter.js';
+import {
+  initChannelAdapters,
+  teardownChannelAdapters,
+  getChannelAdapterForPlatformId,
+  spawnSecretsBackedBots,
+} from './channels/channel-registry.js';
+
+async function main(): Promise<void> {
+  log.info('parachute-agent starting');
+
+  // 1. Init central DB. One-shot relocations run before open:
+  //    - legacy <PROJECT_ROOT>/data/v2.db (pre-0.0.6) → new path
+  //    - legacy <PARACHUTE_DIR>/claw/paraclaw.db (pre-0.1.0) → new path
+  //    - master.key copy from <PARACHUTE_DIR>/claw → <PARACHUTE_DIR>/agent
+  // After that, every host process (including the web server) opens the
+  // new path at <PARACHUTE_DIR>/agent/agent.db.
+  migrateCentralDbLocation();
+  migrateMasterKeyLocation();
+  const db = initDb(CENTRAL_DB_PATH);
+  runMigrations(db);
+  log.info('Central DB ready', { path: CENTRAL_DB_PATH });
+
+  // 1b. One-time filesystem cutovers — idempotent, no-op after first run.
+  migrateGroupsToClaudeLocal();
+  migrateSessionsDir();
+  migrateLegacyLogFilenames(process.cwd());
+  migrateLegacyAllowlistDir();
+
+  // 2. Container runtime
+  ensureContainerRuntimeRunning();
+  cleanupOrphans();
+
+  // 3. Channel adapters
+  await initChannelAdapters((adapter: ChannelAdapter): ChannelSetup => {
+    return {
+      onInbound(platformId, threadId, message) {
+        routeInbound({
+          channelType: adapter.channelType,
+          platformId,
+          threadId,
+          message: {
+            id: message.id,
+            kind: message.kind,
+            content: JSON.stringify(message.content),
+            timestamp: message.timestamp,
+            isMention: message.isMention,
+            isGroup: message.isGroup,
+          },
+        }).catch((err) => {
+          log.error('Failed to route inbound message', { channelType: adapter.channelType, err });
+        });
+      },
+      onInboundEvent(event) {
+        routeInbound(event).catch((err) => {
+          log.error('Failed to route inbound event', {
+            sourceAdapter: adapter.channelType,
+            targetChannelType: event.channelType,
+            err,
+          });
+        });
+      },
+      onMetadata(platformId, name, isGroup) {
+        log.info('Channel metadata discovered', {
+          channelType: adapter.channelType,
+          platformId,
+          name,
+          isGroup,
+        });
+      },
+      onAction(questionId, selectedOption, userId) {
+        dispatchResponse({
+          questionId,
+          value: selectedOption,
+          userId,
+          channelType: adapter.channelType,
+          // platformId/threadId aren't surfaced by the current onAction
+          // signature — registered handlers look them up from the
+          // pending_question / pending_approval row.
+          platformId: '',
+          threadId: null,
+        }).catch((err) => {
+          log.error('Failed to handle question response', { questionId, err });
+        });
+      },
+    };
+  });
+
+  // 3b. Runtime-state migrations that need adapter botIds — copy `.env`
+  // tokens into the secrets table and rewrite legacy v1 messaging_groups
+  // platform_ids to the v2 form. Idempotent; safe across restarts.
+  runStartupBootstrap();
+
+  // 3c. Bring up adapters for every additional bot the operator has
+  // registered via the dynamic register-bot endpoint. Runs after the `.env`
+  // primary is up + bootstrap has populated the secrets table, so we know
+  // the primary's `(channelType, botId)` is already covered and won't be
+  // re-registered.
+  await spawnSecretsBackedBots();
+
+  // 4. Delivery adapter bridge — dispatches to channel adapters
+  const deliveryAdapter = {
+    async deliver(
+      channelType: string,
+      platformId: string,
+      threadId: string | null,
+      kind: string,
+      content: string,
+      files?: import('./channels/adapter.js').OutboundFile[],
+    ): Promise<string | undefined> {
+      const adapter = getChannelAdapterForPlatformId(channelType, platformId);
+      if (!adapter) {
+        log.warn('No adapter for channel type', { channelType, platformId });
+        return;
+      }
+      return adapter.deliver(platformId, threadId, { kind, content: JSON.parse(content), files });
+    },
+    async setTyping(channelType: string, platformId: string, threadId: string | null): Promise<void> {
+      const adapter = getChannelAdapterForPlatformId(channelType, platformId);
+      await adapter?.setTyping?.(platformId, threadId);
+    },
+  };
+  setDeliveryAdapter(deliveryAdapter);
+
+  // 5. Start delivery polls
+  startActiveDeliveryPoll();
+  startSweepDeliveryPoll();
+  log.info('Delivery polls started');
+
+  // 6. Start host sweep
+  startHostSweep();
+  log.info('Host sweep started');
+
+  // 7. Start the web server (single-process boot — replaces the old
+  //    standalone @paraclaw/web-server package).
+  webServer = startWebServer();
+
+  log.info('parachute-agent running');
+}
+
+/** Graceful shutdown. */
+async function shutdown(signal: string): Promise<void> {
+  log.info('Shutdown signal received', { signal });
+  for (const cb of getShutdownCallbacks()) {
+    try {
+      await cb();
+    } catch (err) {
+      log.error('Shutdown callback threw', { err });
+    }
+  }
+  stopDeliveryPolls();
+  stopHostSweep();
+  if (webServer) {
+    await new Promise<void>((resolve) => webServer!.close(() => resolve()));
+    webServer = null;
+  }
+  await teardownChannelAdapters();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+main().catch((err) => {
+  log.fatal('Startup failed', { err });
+  process.exit(1);
+});

package/src/install-slug.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-checkout install identifiers. Lets two parachute-agent installs coexist
+ * on one host without clobbering each other's service registration or the
+ * shared agent image tag.
+ *
+ * Slug is sha1(projectRoot)[:8] — deterministic per checkout path, stable
+ * across re-runs, unique enough across installs.
+ */
+import { createHash } from 'crypto';
+
+export function getInstallSlug(projectRoot: string = process.cwd()): string {
+  return createHash('sha1').update(projectRoot).digest('hex').slice(0, 8);
+}
+
+/** launchd Label + plist basename. e.g. `computer.parachute.agent-ab12cd34`. */
+export function getLaunchdLabel(projectRoot?: string): string {
+  return `computer.parachute.agent-${getInstallSlug(projectRoot)}`;
+}
+
+/** systemd unit name (no .service suffix). e.g. `parachute-agent-ab12cd34`. */
+export function getSystemdUnit(projectRoot?: string): string {
+  return `parachute-agent-${getInstallSlug(projectRoot)}`;
+}
+
+/** Docker image base (no tag). e.g. `parachute-agent-image-ab12cd34`. */
+export function getContainerImageBase(projectRoot?: string): string {
+  return `parachute-agent-image-${getInstallSlug(projectRoot)}`;
+}
+
+/** Default full container image reference with `:latest` tag. */
+export function getDefaultContainerImage(projectRoot?: string): string {
+  return `${getContainerImageBase(projectRoot)}:latest`;
+}

package/src/log.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `migrateLegacyLogFilenames` — idempotent rename of `logs/paraclaw{,.error}.log`
+ * to `logs/parachute-agent{,.error}.log` at host startup. The launchd plist /
+ * systemd unit still controls where the live daemon writes; the migration is
+ * about preserving the historical log file under the new name so tools that
+ * tail the new path see prior entries. See log.ts comment for the supervisor
+ * caveat.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { migrateLegacyLogFilenames } from './log.js';
+
+let scratchRoot: string;
+
+beforeEach(() => {
+  scratchRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-log-migrate-'));
+  fs.mkdirSync(path.join(scratchRoot, 'logs'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(scratchRoot, { recursive: true, force: true });
+});
+
+describe('migrateLegacyLogFilenames', () => {
+  it('renames paraclaw.log + paraclaw.error.log to parachute-agent.* when present', () => {
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'paraclaw.log'), 'normal-history\n');
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'paraclaw.error.log'), 'error-history\n');
+
+    migrateLegacyLogFilenames(scratchRoot);
+
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'), 'utf8')).toBe('normal-history\n');
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.error.log'), 'utf8')).toBe(
+      'error-history\n',
+    );
+    expect(fs.existsSync(path.join(scratchRoot, 'logs', 'paraclaw.log'))).toBe(false);
+    expect(fs.existsSync(path.join(scratchRoot, 'logs', 'paraclaw.error.log'))).toBe(false);
+  });
+
+  it('is a no-op when only the new names exist (post-migration / fresh install)', () => {
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'), 'fresh\n');
+
+    migrateLegacyLogFilenames(scratchRoot);
+
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'), 'utf8')).toBe('fresh\n');
+    expect(fs.existsSync(path.join(scratchRoot, 'logs', 'paraclaw.log'))).toBe(false);
+  });
+
+  it('keeps both files when new+legacy coexist (do not clobber post-migration writes)', () => {
+    // After plist regen the supervisor opens the new file. If the operator
+    // never deleted the orphan `paraclaw.log` from a prior boot, the
+    // migration must NOT overwrite the live `parachute-agent.log` — we
+    // leave both alone so the operator can `rm` the orphan deliberately.
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'paraclaw.log'), 'orphan\n');
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'), 'live\n');
+
+    migrateLegacyLogFilenames(scratchRoot);
+
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'), 'utf8')).toBe('live\n');
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'paraclaw.log'), 'utf8')).toBe('orphan\n');
+  });
+
+  it('handles only one of the two legacy files existing', () => {
+    fs.writeFileSync(path.join(scratchRoot, 'logs', 'paraclaw.error.log'), 'errors-only\n');
+
+    migrateLegacyLogFilenames(scratchRoot);
+
+    expect(fs.existsSync(path.join(scratchRoot, 'logs', 'parachute-agent.log'))).toBe(false);
+    expect(fs.readFileSync(path.join(scratchRoot, 'logs', 'parachute-agent.error.log'), 'utf8')).toBe('errors-only\n');
+  });
+
+  it('is a no-op on a missing logs/ directory', () => {
+    fs.rmSync(path.join(scratchRoot, 'logs'), { recursive: true, force: true });
+
+    expect(() => migrateLegacyLogFilenames(scratchRoot)).not.toThrow();
+    expect(fs.existsSync(path.join(scratchRoot, 'logs'))).toBe(false);
+  });
+});