@cnrai/pave 0.3.32 → 0.3.34

package/test/soul-reinject.test.js

@@ -0,0 +1,1027 @@
+/**
+ * Tests for SOUL re-injection behavior in agent mode (issue #101)
+ *
+ * Verifies:
+ * - Hot-reload: SOUL file changes are detected and re-sent
+ * - Periodic re-injection: SOUL is re-sent every N iterations to prevent drift
+ * - Post-compaction re-injection: SOUL is re-sent after auto-compaction
+ * - --reinject-interval parsing
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Import args parser for --reinject-interval tests
+const { parseArgs } = require('../lib/args-parser');
+
+// Import simpleHash for SOUL content change detection (sandbox-compatible)
+const { simpleHash } = require('../lib/hash');
+
+// Helper to create a temporary SOUL file
+function createTempSoulFile(content) {
+  const tmpDir = os.tmpdir();
+  const soulPath = path.join(tmpDir, `test-soul-reinject-${Date.now()}-${Math.random().toString(36).slice(2)}.md`);
+  fs.writeFileSync(soulPath, content, 'utf8');
+  return soulPath;
+}
+
+// Helper to clean up temp files
+function removeTempFile(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  } catch (e) {
+    // Ignore cleanup errors
+  }
+}
+
+/**
+ * Simulate the per-iteration SOUL read + message decision logic with re-injection support.
+ * This mirrors the updated code inside the while(running) loop (issue #101):
+ *   1. Re-read SOUL file
+ *   2. Compute hash via simpleHash, detect changes
+ *   3. Increment iterationsSinceSoulSent
+ *   4. Determine message based on: first send, file change, force reinject, periodic reinject, or "keep going"
+ *   5. After successful send, update state accordingly
+ *
+ * @param {string} soulPath - Path to the SOUL file
+ * @param {object} state - Mutable state:
+ *   { soulSent: boolean, lastSoulHash: string|null, iterationsSinceSoulSent: number, forceReinject: boolean }
+ * @param {object} [opts]
+ * @param {boolean} [opts.sendSuccess=true] - Simulate whether the send succeeds
+ * @param {number} [opts.reinjectInterval=10] - SOUL_REINJECT_INTERVAL
+ * @param {boolean} [opts.isNewSession=true] - Whether this is a new session or resumed
+ * @returns {{ message, soulSent, error, sendingSoul, readContent, soulChanged, shouldReinject, forceReinject, soulTrigger }}
+ */
+function simulateIteration(soulPath, state, opts) {
+  const sendSuccess = (opts && opts.sendSuccess !== undefined) ? opts.sendSuccess : true;
+  const SOUL_REINJECT_INTERVAL = (opts && opts.reinjectInterval) || 10;
+
+  let soulContent;
+  try {
+    soulContent = fs.readFileSync(soulPath, 'utf8');
+  } catch (err) {
+    return {
+      message: null,
+      soulSent: state.soulSent,
+      error: err,
+      readContent: null,
+      soulChanged: false,
+      shouldReinject: false,
+      forceReinject: state.forceReinject,
+      soulTrigger: null,
+    };
+  }
+
+  // Compute hash (state mutation deferred until after successful send)
+  const currentSoulHash = simpleHash(soulContent);
+  const soulChanged = state.lastSoulHash !== null && currentSoulHash !== state.lastSoulHash;
+
+  // Tentatively compute periodic check
+  const tentativeCounter = state.iterationsSinceSoulSent + 1;
+  const shouldReinject = state.soulSent && tentativeCounter >= SOUL_REINJECT_INTERVAL;
+
+  const sendingSoul = !state.soulSent;
+  let message;
+  let soulTrigger = null;
+  const isNewSession = (opts && opts.isNewSession !== undefined) ? opts.isNewSession : true;
+  if (sendingSoul) {
+    if (isNewSession) {
+      message = soulContent;
+    } else {
+      message = 'You are resuming from a previous session. Here are your instructions:\n\n' + soulContent;
+    }
+    soulTrigger = 'first';
+  } else if (soulChanged) {
+    message = 'SOUL instructions have been updated. Here are the new instructions:\n\n' + soulContent;
+    soulTrigger = 'hotReload';
+  } else if (state.forceReinject) {
+    message = 'Reminder -- here are your core instructions. Follow them:\n\n' + soulContent;
+    soulTrigger = 'compaction';
+  } else if (shouldReinject) {
+    message = 'Reminder -- here are your core instructions. Follow them:\n\n' + soulContent;
+    soulTrigger = 'periodic';
+  } else {
+    message = 'keep going';
+  }
+
+  // Simulate send success/failure -- only commit state on success
+  if (sendSuccess) {
+    state.lastSoulHash = currentSoulHash;
+    if (soulTrigger === 'first') {
+      state.soulSent = true;
+      state.iterationsSinceSoulSent = 0;
+    } else if (soulTrigger === 'hotReload') {
+      state.iterationsSinceSoulSent = 0;
+    } else if (soulTrigger === 'compaction') {
+      state.iterationsSinceSoulSent = 0;
+    } else if (soulTrigger === 'periodic') {
+      state.iterationsSinceSoulSent = 0;
+    } else {
+      // "keep going"
+      state.iterationsSinceSoulSent++;
+    }
+    // Any successful SOUL delivery clears forceReinject
+    if (soulTrigger) {
+      state.forceReinject = false;
+    }
+  } else if (!soulTrigger) {
+    // Failed "keep going" -- advance counter and hash anyway
+    state.iterationsSinceSoulSent++;
+    state.lastSoulHash = currentSoulHash;
+  }
+  // On failure with a soulTrigger: state is NOT mutated, so the trigger retries
+
+  return {
+    message,
+    soulSent: state.soulSent,
+    error: null,
+    sendingSoul,
+    readContent: soulContent,
+    soulChanged,
+    shouldReinject,
+    forceReinject: state.forceReinject,
+    soulTrigger,
+  };
+}
+
+/** Create a fresh state object for a new session */
+function newSessionState() {
+  return {
+    soulSent: false,
+    lastSoulHash: null,
+    iterationsSinceSoulSent: 0,
+    forceReinject: false,
+  };
+}
+
+/** Create a fresh state object for a resumed session (issue #194: soulSent=false to force re-injection) */
+function resumedSessionState() {
+  return {
+    soulSent: false,
+    lastSoulHash: null,
+    iterationsSinceSoulSent: 0,
+    forceReinject: false,
+  };
+}
+
+// =============================================================================
+// Args Parser Tests
+// =============================================================================
+
+describe('--reinject-interval argument parsing', () => {
+  test('default reinjectInterval is null when not provided', () => {
+    const args = parseArgs(['agent', 'SOUL.md']);
+    expect(args.reinjectInterval).toBeNull();
+  });
+
+  test('parses --reinject-interval with valid integer', () => {
+    const args = parseArgs(['agent', '--reinject-interval', '5', 'SOUL.md']);
+    expect(args.reinjectInterval).toBe(5);
+  });
+
+  test('parses --reinject-interval 1 (minimum)', () => {
+    const args = parseArgs(['agent', '--reinject-interval', '1', 'SOUL.md']);
+    expect(args.reinjectInterval).toBe(1);
+  });
+
+  test('parses --reinject-interval 100 (large value)', () => {
+    const args = parseArgs(['agent', '--reinject-interval', '100', 'SOUL.md']);
+    expect(args.reinjectInterval).toBe(100);
+  });
+
+  test('--reinject-interval appears in flagsWithValues (not treated as SOUL path)', () => {
+    const args = parseArgs(['agent', '--reinject-interval', '5', 'SOUL.md']);
+    // If --reinject-interval is in flagsWithValues, '5' is consumed as its value,
+    // and 'SOUL.md' is correctly captured as the positional arg
+    expect(args.reinjectInterval).toBe(5);
+    expect(args.commandArgs[0]).toBe('SOUL.md');
+  });
+
+  test('--reinject-interval with missing value exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  test('--reinject-interval with non-integer exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval', 'abc'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  test('--reinject-interval with zero exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval', '0'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  test('--reinject-interval with negative value exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval', '-1'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  test('--reinject-interval with partially numeric value exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval', '10abc'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  test('--reinject-interval with scientific notation exits', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const mockError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => parseArgs(['agent', '--reinject-interval', '1e3'])).toThrow('process.exit called');
+
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+});
+
+// =============================================================================
+// Hot-reload Tests (SOUL file change detection)
+// =============================================================================
+
+describe('SOUL hot-reload on file change (issue #101)', () => {
+  test('detects SOUL file change and sends updated content', () => {
+    const soulPath = createTempSoulFile('# SOUL v1\nDo task A');
+    try {
+      const state = newSessionState();
+
+      // Iteration 1: first send
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.message).toBe('# SOUL v1\nDo task A');
+      expect(r1.sendingSoul).toBe(true);
+      expect(r1.soulChanged).toBe(false); // No previous hash to compare
+
+      // Iteration 2: keep going (no change)
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.message).toBe('keep going');
+      expect(r2.soulChanged).toBe(false);
+
+      // User edits SOUL file
+      fs.writeFileSync(soulPath, '# SOUL v2\nDo task B instead', 'utf8');
+
+      // Iteration 3: detects change and sends updated SOUL
+      const r3 = simulateIteration(soulPath, state);
+      expect(r3.soulChanged).toBe(true);
+      expect(r3.message).toContain('SOUL instructions have been updated');
+      expect(r3.message).toContain('# SOUL v2');
+      expect(r3.message).toContain('Do task B instead');
+
+      // Iteration 4: back to keep going (no change)
+      const r4 = simulateIteration(soulPath, state);
+      expect(r4.message).toBe('keep going');
+      expect(r4.soulChanged).toBe(false);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('multiple SOUL file changes are each detected', () => {
+    const soulPath = createTempSoulFile('v1');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going
+
+      // Change 1
+      fs.writeFileSync(soulPath, 'v2', 'utf8');
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.soulChanged).toBe(true);
+      expect(r1.message).toContain('v2');
+
+      // Change 2
+      fs.writeFileSync(soulPath, 'v3', 'utf8');
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.soulChanged).toBe(true);
+      expect(r2.message).toContain('v3');
+
+      // No change
+      const r3 = simulateIteration(soulPath, state);
+      expect(r3.soulChanged).toBe(false);
+      expect(r3.message).toBe('keep going');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('SOUL change resets iterationsSinceSoulSent counter', () => {
+    const soulPath = createTempSoulFile('original');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      // Run 5 more iterations
+      for (let i = 0; i < 5; i++) {
+        simulateIteration(soulPath, state);
+      }
+      expect(state.iterationsSinceSoulSent).toBe(5);
+
+      // Change SOUL
+      fs.writeFileSync(soulPath, 'updated', 'utf8');
+      simulateIteration(soulPath, state);
+      expect(state.iterationsSinceSoulSent).toBe(0); // Reset after change
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('SOUL file change on first iteration (before first send) does not count as change', () => {
+    const soulPath = createTempSoulFile('initial content');
+    try {
+      const state = newSessionState();
+
+      // First iteration: no previous hash, so soulChanged should be false
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.soulChanged).toBe(false);
+      expect(r1.sendingSoul).toBe(true);
+      expect(r1.message).toBe('initial content');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Periodic Re-injection Tests
+// =============================================================================
+
+describe('Periodic SOUL re-injection (issue #101)', () => {
+  test('re-injects SOUL after N iterations (default 10)', () => {
+    const soulPath = createTempSoulFile('# Core Instructions');
+    try {
+      const state = newSessionState();
+
+      // First send
+      simulateIteration(soulPath, state);
+      expect(state.soulSent).toBe(true);
+
+      // Iterations 2-10: keep going
+      for (let i = 0; i < 9; i++) {
+        const r = simulateIteration(soulPath, state);
+        expect(r.message).toBe('keep going');
+      }
+
+      // Iteration 11: periodic re-injection (10 iterations since last SOUL send)
+      const r = simulateIteration(soulPath, state);
+      expect(r.shouldReinject).toBe(true);
+      expect(r.message).toContain('Reminder -- here are your core instructions');
+      expect(r.message).toContain('# Core Instructions');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('re-injection counter resets after periodic re-injection', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+
+      // Run to first re-injection (10 iterations)
+      for (let i = 0; i < 9; i++) simulateIteration(soulPath, state);
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.shouldReinject).toBe(true);
+      expect(state.iterationsSinceSoulSent).toBe(0);
+
+      // Next 9 iterations should be "keep going"
+      for (let i = 0; i < 9; i++) {
+        const r = simulateIteration(soulPath, state);
+        expect(r.message).toBe('keep going');
+      }
+
+      // 10th iteration after reset: re-inject again
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.shouldReinject).toBe(true);
+      expect(r2.message).toContain('Reminder');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('custom reinject interval of 3', () => {
+    const soulPath = createTempSoulFile('# Custom Interval');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 3 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // 2 keep-going iterations
+      simulateIteration(soulPath, state, opts);
+      simulateIteration(soulPath, state, opts);
+
+      // 3rd iteration since last SOUL send: re-inject
+      const r = simulateIteration(soulPath, state, opts);
+      expect(r.shouldReinject).toBe(true);
+      expect(r.message).toContain('Reminder');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('custom reinject interval of 1 (every iteration)', () => {
+    const soulPath = createTempSoulFile('# Always');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 1 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Every subsequent iteration should re-inject
+      for (let i = 0; i < 5; i++) {
+        const r = simulateIteration(soulPath, state, opts);
+        expect(r.message).toContain('Reminder');
+      }
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('resumed session sends SOUL on first iteration with resume prefix (issue #194)', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = resumedSessionState();
+
+      // First iteration of resumed session: should send SOUL with resume prefix
+      const r = simulateIteration(soulPath, state, { isNewSession: false });
+      expect(r.sendingSoul).toBe(true);
+      expect(r.soulTrigger).toBe('first');
+      expect(r.message).toContain('You are resuming from a previous session');
+      expect(r.message).toContain('# SOUL');
+      expect(state.soulSent).toBe(true);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Post-Compaction Re-injection Tests
+// =============================================================================
+
+describe('Post-compaction SOUL re-injection (issue #101)', () => {
+  test('forceReinject causes SOUL re-send on next iteration', () => {
+    const soulPath = createTempSoulFile('# SOUL Instructions');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going
+
+      // Simulate compaction: set forceReinject
+      state.forceReinject = true;
+
+      const r = simulateIteration(soulPath, state);
+      expect(r.message).toContain('Reminder -- here are your core instructions');
+      expect(r.message).toContain('# SOUL Instructions');
+      expect(state.forceReinject).toBe(false); // Flag is cleared after use
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('forceReinject resets iterationsSinceSoulSent', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+
+      // Run 7 iterations
+      for (let i = 0; i < 7; i++) simulateIteration(soulPath, state);
+      expect(state.iterationsSinceSoulSent).toBe(7);
+
+      // Compaction happens
+      state.forceReinject = true;
+      simulateIteration(soulPath, state);
+      expect(state.iterationsSinceSoulSent).toBe(0);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('forceReinject is only consumed once', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going
+
+      state.forceReinject = true;
+
+      // First iteration after compaction: re-inject
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.message).toContain('Reminder');
+
+      // Next iteration: back to keep going
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.message).toBe('keep going');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('forceReinject takes priority over periodic re-injection timing', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 5 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Run 4 iterations (1 less than reinject interval)
+      for (let i = 0; i < 4; i++) simulateIteration(soulPath, state, opts);
+
+      // Both forceReinject and periodic would trigger -- forceReinject takes priority
+      state.forceReinject = true;
+      state.iterationsSinceSoulSent = 10; // Would also trigger periodic
+
+      const r = simulateIteration(soulPath, state, opts);
+      expect(r.message).toContain('Reminder');
+      expect(state.forceReinject).toBe(false);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Priority Order Tests
+// =============================================================================
+
+describe('SOUL message priority order (issue #101)', () => {
+  test('first send takes highest priority', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      state.forceReinject = true; // Would trigger reinject
+      state.iterationsSinceSoulSent = 100; // Would trigger periodic
+
+      const r = simulateIteration(soulPath, state);
+      // First send (sendingSoul) takes priority over all other conditions
+      expect(r.sendingSoul).toBe(true);
+      expect(r.message).toBe('# SOUL');
+      expect(r.message).not.toContain('Reminder');
+      expect(r.message).not.toContain('updated');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('SOUL file change takes priority over forceReinject and periodic', () => {
+    const soulPath = createTempSoulFile('v1');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // establish hash
+
+      // Set up conditions for all three triggers
+      fs.writeFileSync(soulPath, 'v2', 'utf8');
+      state.forceReinject = true;
+      state.iterationsSinceSoulSent = 100;
+
+      const r = simulateIteration(soulPath, state);
+      expect(r.soulChanged).toBe(true);
+      expect(r.message).toContain('SOUL instructions have been updated');
+      expect(r.message).toContain('v2');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('forceReinject takes priority over periodic re-injection', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 2 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Set up both force and periodic
+      state.forceReinject = true;
+      state.iterationsSinceSoulSent = 100;
+
+      const r = simulateIteration(soulPath, state, opts);
+      // forceReinject is consumed (set to false) -- verifies force path was taken
+      expect(state.forceReinject).toBe(false);
+      expect(r.message).toContain('Reminder');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('hot-reload clears forceReinject to prevent redundant post-compaction reminder', () => {
+    const soulPath = createTempSoulFile('v1');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going (establishes hash)
+
+      // Compaction sets forceReinject, AND user also edits SOUL file
+      state.forceReinject = true;
+      fs.writeFileSync(soulPath, 'v2', 'utf8');
+
+      // Hot-reload fires (higher priority than forceReinject)
+      const r1 = simulateIteration(soulPath, state);
+      expect(r1.soulTrigger).toBe('hotReload');
+      expect(r1.message).toContain('SOUL instructions have been updated');
+      expect(r1.message).toContain('v2');
+      // forceReinject should be cleared because SOUL was delivered
+      expect(state.forceReinject).toBe(false);
+
+      // Next iteration: just "keep going" (no redundant compaction reminder)
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.message).toBe('keep going');
+      expect(r2.soulTrigger).toBeNull();
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('periodic re-injection clears forceReinject', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 2 };
+
+      simulateIteration(soulPath, state, opts); // first send
+      simulateIteration(soulPath, state, opts); // keep going
+
+      // Set forceReinject AND counter triggers periodic
+      state.forceReinject = true;
+
+      // forceReinject fires (higher priority) and clears itself
+      const r = simulateIteration(soulPath, state, opts);
+      expect(r.soulTrigger).toBe('compaction');
+      expect(state.forceReinject).toBe(false);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Edge Cases
+// =============================================================================
+
+describe('SOUL re-injection edge cases (issue #101)', () => {
+  test('SOUL file becomes unreadable does not crash hash tracking', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      const hashAfterFirstSend = state.lastSoulHash;
+
+      // File becomes unreadable
+      fs.unlinkSync(soulPath);
+      const r = simulateIteration(soulPath, state);
+      expect(r.error).not.toBeNull();
+      expect(state.lastSoulHash).toBe(hashAfterFirstSend); // Hash unchanged
+
+      // File comes back with same content
+      fs.writeFileSync(soulPath, '# SOUL', 'utf8');
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.soulChanged).toBe(false); // Same content, no change
+      expect(r2.message).toBe('keep going');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('SOUL file becomes unreadable then returns with different content', () => {
+    const soulPath = createTempSoulFile('# SOUL v1');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // establish hash
+
+      // File becomes unreadable
+      fs.unlinkSync(soulPath);
+      simulateIteration(soulPath, state); // error, hash unchanged
+
+      // File comes back with DIFFERENT content
+      fs.writeFileSync(soulPath, '# SOUL v2', 'utf8');
+      const r = simulateIteration(soulPath, state);
+      expect(r.soulChanged).toBe(true);
+      expect(r.message).toContain('SOUL instructions have been updated');
+      expect(r.message).toContain('# SOUL v2');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('empty SOUL file is handled correctly', () => {
+    const soulPath = createTempSoulFile('');
+    try {
+      const state = newSessionState();
+
+      const r = simulateIteration(soulPath, state);
+      expect(r.message).toBe('');
+      expect(r.sendingSoul).toBe(true);
+      expect(state.lastSoulHash).not.toBeNull();
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('very large reinject interval (1000) works correctly', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 1000 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Run 999 iterations
+      for (let i = 0; i < 999; i++) {
+        const r = simulateIteration(soulPath, state, opts);
+        expect(r.message).toBe('keep going');
+      }
+
+      // 1000th iteration: re-inject
+      const r = simulateIteration(soulPath, state, opts);
+      expect(r.shouldReinject).toBe(true);
+      expect(r.message).toContain('Reminder');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Failed Send Retry Tests (deferred state mutation)
+// =============================================================================
+
+describe('SOUL re-injection retries on send failure (issue #101)', () => {
+  test('failed hot-reload send retries on next iteration', () => {
+    const soulPath = createTempSoulFile('v1');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going (establishes hash)
+
+      // Change SOUL file
+      fs.writeFileSync(soulPath, 'v2', 'utf8');
+
+      // Send fails -- hot-reload should NOT be consumed
+      const r1 = simulateIteration(soulPath, state, { sendSuccess: false });
+      expect(r1.soulTrigger).toBe('hotReload');
+      expect(r1.message).toContain('SOUL instructions have been updated');
+      // Hash should NOT have been committed
+      expect(state.lastSoulHash).not.toBe(simpleHash('v2'));
+
+      // Next iteration: hot-reload retries because hash wasn't committed
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.soulChanged).toBe(true);
+      expect(r2.soulTrigger).toBe('hotReload');
+      expect(r2.message).toContain('SOUL instructions have been updated');
+      expect(r2.message).toContain('v2');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('failed forceReinject send retries on next iteration', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      simulateIteration(soulPath, state); // first send
+      simulateIteration(soulPath, state); // keep going
+
+      // Simulate compaction
+      state.forceReinject = true;
+
+      // Send fails -- forceReinject should NOT be consumed
+      const r1 = simulateIteration(soulPath, state, { sendSuccess: false });
+      expect(r1.soulTrigger).toBe('compaction');
+      expect(state.forceReinject).toBe(true); // NOT consumed
+
+      // Next iteration: forceReinject retries
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.soulTrigger).toBe('compaction');
+      expect(r2.message).toContain('Reminder');
+      expect(state.forceReinject).toBe(false); // NOW consumed
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('failed periodic reinject send retries on next iteration', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 3 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Run 2 keep-going iterations
+      simulateIteration(soulPath, state, opts);
+      simulateIteration(soulPath, state, opts);
+
+      // 3rd iteration: periodic re-inject, but send fails
+      const r1 = simulateIteration(soulPath, state, { ...opts, sendSuccess: false });
+      expect(r1.soulTrigger).toBe('periodic');
+      expect(r1.message).toContain('Reminder');
+      // Counter should NOT have been reset
+      expect(state.iterationsSinceSoulSent).toBe(2); // Still at pre-trigger value
+
+      // Next iteration: periodic re-inject retries (counter still >= interval)
+      const r2 = simulateIteration(soulPath, state, opts);
+      expect(r2.soulTrigger).toBe('periodic');
+      expect(r2.message).toContain('Reminder');
+      expect(state.iterationsSinceSoulSent).toBe(0); // NOW reset
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('failed first SOUL send retries (existing behavior preserved)', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+
+      // Send fails
+      const r1 = simulateIteration(soulPath, state, { sendSuccess: false });
+      expect(r1.soulTrigger).toBe('first');
+      expect(r1.message).toBe('# SOUL');
+      expect(state.soulSent).toBe(false); // NOT marked as sent
+
+      // Retry succeeds
+      const r2 = simulateIteration(soulPath, state);
+      expect(r2.soulTrigger).toBe('first');
+      expect(r2.message).toBe('# SOUL');
+      expect(state.soulSent).toBe(true); // NOW marked as sent
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('failed send does not advance counter for keep-going on SOUL trigger', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = newSessionState();
+      const opts = { reinjectInterval: 5 };
+
+      simulateIteration(soulPath, state, opts); // first send
+
+      // Run 4 keep-going iterations
+      for (let i = 0; i < 4; i++) simulateIteration(soulPath, state, opts);
+      expect(state.iterationsSinceSoulSent).toBe(4);
+
+      // Trigger periodic (counter = 5 >= interval 5), but fail
+      const r = simulateIteration(soulPath, state, { ...opts, sendSuccess: false });
+      expect(r.soulTrigger).toBe('periodic');
+      // Counter should NOT have advanced past the pre-trigger value
+      expect(state.iterationsSinceSoulSent).toBe(4);
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});
+
+// =============================================================================
+// Resumed Session SOUL Re-injection Tests (Issue #194)
+// =============================================================================
+
+describe('SOUL re-injection on resumed session (issue #194)', () => {
+  test('resumed session message includes resume prefix', () => {
+    const soulPath = createTempSoulFile('Do the work');
+    try {
+      const state = resumedSessionState();
+
+      const r = simulateIteration(soulPath, state, { isNewSession: false });
+      expect(r.message).toBe('You are resuming from a previous session. Here are your instructions:\n\n' + 'Do the work');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('new session does NOT include resume prefix', () => {
+    const soulPath = createTempSoulFile('Do the work');
+    try {
+      const state = newSessionState();
+
+      const r = simulateIteration(soulPath, state, { isNewSession: true });
+      expect(r.message).toBe('Do the work');
+      expect(r.message).not.toContain('resuming');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('resumed session periodic re-injection works after first send', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = resumedSessionState();
+      const opts = { reinjectInterval: 3, isNewSession: false };
+
+      // First iteration: SOUL sent with resume prefix
+      const r1 = simulateIteration(soulPath, state, opts);
+      expect(r1.sendingSoul).toBe(true);
+      expect(state.soulSent).toBe(true);
+
+      // Next 2 iterations: keep going
+      simulateIteration(soulPath, state, opts);
+      simulateIteration(soulPath, state, opts);
+
+      // 4th iteration (3 since last SOUL): periodic re-injection
+      const r4 = simulateIteration(soulPath, state, opts);
+      expect(r4.shouldReinject).toBe(true);
+      expect(r4.message).toContain('Reminder');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('resumed session hot-reload works after first send', () => {
+    const soulPath = createTempSoulFile('v1');
+    try {
+      const state = resumedSessionState();
+      const opts = { isNewSession: false };
+
+      // First iteration: SOUL sent
+      simulateIteration(soulPath, state, opts);
+
+      // Keep going to establish hash
+      simulateIteration(soulPath, state, opts);
+
+      // Change SOUL file
+      fs.writeFileSync(soulPath, 'v2', 'utf8');
+
+      // Hot-reload detected
+      const r = simulateIteration(soulPath, state, opts);
+      expect(r.soulChanged).toBe(true);
+      expect(r.message).toContain('SOUL instructions have been updated');
+      expect(r.message).toContain('v2');
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+
+  test('failed first send on resumed session retries', () => {
+    const soulPath = createTempSoulFile('# SOUL');
+    try {
+      const state = resumedSessionState();
+      const opts = { isNewSession: false, sendSuccess: false };
+
+      // First iteration fails
+      const r1 = simulateIteration(soulPath, state, opts);
+      expect(r1.soulTrigger).toBe('first');
+      expect(state.soulSent).toBe(false); // NOT marked as sent
+
+      // Retry succeeds
+      const r2 = simulateIteration(soulPath, state, { isNewSession: false });
+      expect(r2.soulTrigger).toBe('first');
+      expect(r2.message).toContain('You are resuming from a previous session');
+      expect(state.soulSent).toBe(true); // NOW marked as sent
+    } finally {
+      removeTempFile(soulPath);
+    }
+  });
+});