Release 3.3.0: harden loop handoff feedback

lib/mini-ralph/history.js

@@ -52,6 +52,10 @@ function read(ralphDir) {
  * @param {Array}  entry.toolUsage         - Tool usage summary array
  * @param {Array}  entry.filesChanged      - Files changed in this iteration
  * @param {number} entry.exitCode          - OpenCode exit code
+ * @param {boolean} [entry.blockedHandoffDetected] - Whether the iteration emitted
+ *   the configured blocked-handoff promise and stopped for operator action.
+ * @param {string}  [entry.blockedHandoffNote] - Compact, single-line preview of
+ *   the extracted blocker note. The full note is persisted in HANDOFF.md.
  * @param {number} [entry.promptBytes]     - UTF-8 byte length of the assembled prompt
  * @param {number} [entry.promptChars]     - Character length of the assembled prompt
  * @param {number} [entry.promptTokens]    - Estimated token count for the prompt (chars/4, rounded)

lib/mini-ralph/index.js

@@ -35,6 +35,7 @@ const prompt = require('./prompt');
  * @param {number} [options.maxIterations]   - Maximum iterations (default: 50)
  * @param {string} [options.completionPromise] - Promise string signaling loop completion (default: "COMPLETE")
  * @param {string} [options.taskPromise]     - Promise string signaling task completion (default: "READY_FOR_NEXT_TASK")
+ * @param {string} [options.blockedHandoffPromise] - Promise string signaling the agent is blocked and requesting human handoff (default: "BLOCKED_HANDOFF")
  * @param {boolean} [options.tasksMode]      - Enable tasks mode (default: false)
  * @param {string} [options.tasksFile]       - Path to tasks file when tasksMode is true
  * @param {boolean} [options.noCommit]       - Suppress auto-commit (default: false)