taskforce-loop-engineering 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.8.0 - 2026-08-07
+
+- Add project-aware completion semantics: accepted milestones return project tasks to `inbox/` as `project_in_progress` until an explicit project terminal contract is accepted.
+- Replace filename/tail-based checkpoint judgement with milestone lineage, revision ancestry, sequence, and recency so resolved historical blockers and `cp10` ordering cannot corrupt the final judgement.
+- Separate current blockers from `deferred_gates`, and preserve future authorization boundaries without blocking safe local backlog work.
+- Add a durable human-input lifecycle with a distinct `waiting/` queue state. Inputs received while queued, active, failed, or canceled are delivered on the next safe tick, consumed once, and closed by a successor checkpoint.
+- Keep one-time secrets out of task bodies and ordinary JSON artifacts. Store them in permission-restricted temporary files, pass only references and hashes, and destroy plaintext after dispatch.
+- Recover orphaned `active/` tasks immediately after a new runner acquires the queue lock. The task is atomically returned to `inbox/`, recovery metadata is retained, and the same tick resumes from durable checkpoints instead of leaving a zombie active task until the stale timeout.
+- Add required scheduler heartbeat health checks. A queue with `scheduler.required=true` and queued work now fails `doctor` with `scheduler_missing` when no fresh external scheduler tick has been observed.
+- Add regression coverage for project continuation, checkpoint lineage and ordering, human-input state transitions and redaction, orphan recovery, and scheduler heartbeat fail-closed behavior.
+
+## 0.7.2 - 2026-08-06
+
+- Keep `ready_for_human_review` tasks out of `done/` until an explicit human decision is recorded; emit a scoped acceptance notification, fail closed when delivery routing is missing, and transition approved tasks to `completed` only after approval.
+- Forward configured human-gate policy into generated task contracts so queue state and final judgement agree.
+- Add regression coverage for the complete `ready_for_human_review → approve → completed` lifecycle.
+
 ## 0.7.1 - 2026-08-05
 
 - Make the standalone ClawHub skill self-sufficient by documenting the official npm package, GitHub repository, Node.js requirement, license, and installation commands.

package/lib/core.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -785,6 +786,24 @@ export async function doctorReport(root, options = {}) {
         preflightConfig: optionsForQueue.preflightConfig ?? null,
         status
       });
+      if (config.scheduler?.required === true && status.queued > 0) {
+        const schedulerState = await readQueueSchedulerState(root, optionsForQueue.queue);
+        const heartbeatMaxAgeMs = parseScheduleDurationMs(
+          config.scheduler.heartbeatMaxAge ?? '5m',
+          'scheduler.heartbeatMaxAge'
+        );
+        const generatedAtMs = Date.parse(schedulerState?.generatedAt ?? '');
+        const ageMs = Number.isFinite(generatedAtMs) ? Math.max(0, Date.now() - generatedAtMs) : null;
+        const healthy = ageMs !== null && ageMs <= heartbeatMaxAgeMs;
+        add(`queue:${optionsForQueue.queue}:scheduler-heartbeat`, 'fail', healthy, {
+          code: healthy ? 'scheduler_healthy' : 'scheduler_missing',
+          queued: status.queued,
+          state: path.relative(root, queueSchedulerStatePath(root, optionsForQueue.queue)),
+          generatedAt: schedulerState?.generatedAt ?? null,
+          ageMs,
+          heartbeatMaxAgeMs
+        });
+      }
       if (status.locked) add(`queue:${optionsForQueue.queue}:lock`, 'warn', false, status.lockExpiresAt);
       if (status.active > 0) add(`queue:${optionsForQueue.queue}:active`, 'warn', false, `${status.active} active task(s)`);
       if (status.failed > 0) add(`queue:${optionsForQueue.queue}:failed`, 'warn', false, `${status.failed} failed task(s)`);
@@ -924,7 +943,7 @@ export function queueSubdirFor(root, queue, subdir) {
 
 export async function ensureQueueDirs(root, queue) {
   normalizeLoopId(queue);
-  await Promise.all(['inbox', 'active', 'done', 'failed', 'runs', 'canceled', 'tasks']
+  await Promise.all(['inbox', 'active', 'waiting', 'done', 'failed', 'runs', 'canceled', 'tasks']
     .map((subdir) => mkdir(queueSubdirFor(root, queue, subdir), { recursive: true })));
 }
 
@@ -1422,14 +1441,15 @@ export async function projectStatus(root, options = {}) {
     backlog = null;
   }
   const totals = queues.reduce((acc, queue) => {
-    for (const key of ['queued', 'active', 'done', 'failed', 'canceled', 'runs']) {
+    for (const key of ['queued', 'active', 'waiting', 'done', 'failed', 'canceled', 'runs']) {
       acc[key] += queue.status[key] ?? 0;
     }
     if (queue.status.locked) acc.locked += 1;
     return acc;
-  }, { queued: 0, active: 0, done: 0, failed: 0, canceled: 0, runs: 0, locked: 0 });
+  }, { queued: 0, active: 0, waiting: 0, done: 0, failed: 0, canceled: 0, runs: 0, locked: 0 });
   const needsAttention = [];
   if (totals.failed > 0) needsAttention.push('failed_tasks_present');
+  if (totals.waiting > 0) needsAttention.push('human_input_waiting');
   if (totals.active > 0) needsAttention.push('active_tasks_present');
   if (queues.some((queue) => queue.status.locked)) needsAttention.push('queue_locked');
   return {
@@ -1673,13 +1693,20 @@ export async function routeLoopMessage(root, options = {}) {
 }
 
 function terminalNotificationMessage(queue, task) {
-  const needsHuman = ['needs_human_input', 'blocked'].includes(task.status);
+  const needsReview = task.status === 'ready_for_human_review';
+  const needsHuman = ['needs_human_input', 'blocked', 'ready_for_human_review'].includes(task.status);
   return [
-    needsHuman ? 'Loop task needs human input' : 'Loop task reached a terminal state',
+    needsReview ? 'Loop task is ready for human acceptance'
+      : needsHuman ? 'Loop task needs human input'
+        : 'Loop task reached a terminal state',
     `task: ${task.title}`,
     `queue: ${queue}`,
     `status: ${task.status}`,
-    ...(needsHuman ? ['next: inspect the task final judgement and checkpoints, resolve the blocker, then explicitly continue or requeue.'] : [])
+    ...(needsReview
+      ? [`next: review the final judgement and record approve, request_changes, or reject for task ${task.id}.`]
+      : needsHuman
+        ? ['next: inspect the task final judgement and checkpoints, resolve the blocker, then explicitly continue or requeue.']
+        : [])
   ].join('\n');
 }
 
@@ -1696,7 +1723,16 @@ export async function notifyTerminalTasks(root, options = {}) {
     const dir = queueSubdirFor(root, queue, subdir);
     for (const file of await listJson(dir)) {
       const task = await readJson(path.join(dir, file));
-      if (!task?.source || !task?.id || !task?.status) continue;
+      if (!task?.id || !task?.status) continue;
+      if (!task?.source?.channel || !task?.source?.target) {
+        results.push({
+          taskId: task.id,
+          status: task.status,
+          outcome: 'failed',
+          error: 'missing source.channel/source.target; refusing unscoped terminal delivery'
+        });
+        continue;
+      }
       const key = `${safeTaskId(task.id)}.${normalizeLoopId(task.status)}.json`;
       const ledgerFile = path.join(notificationDir, key);
       if (await exists(ledgerFile)) {
@@ -1764,7 +1800,7 @@ function humanInputMessage(queue, task, checkpoint, gateId) {
 
 async function tasksById(root, queue) {
   const tasks = new Map();
-  for (const subdir of ['inbox', 'active', 'done', 'failed', 'canceled']) {
+  for (const subdir of ['inbox', 'active', 'waiting', 'done', 'failed', 'canceled']) {
     for (const file of await listJson(queueSubdirFor(root, queue, subdir))) {
       const task = await readJson(path.join(queueSubdirFor(root, queue, subdir), file));
       if (task?.id) tasks.set(task.id, { task, subdir });
@@ -1794,6 +1830,19 @@ export async function notifyHumanInputRequests(root, options = {}) {
       const ledgerFile = path.join(gatesDir, `${safeTaskId(taskId)}.${normalizeLoopId(checkpointId)}.json`);
       if (await exists(ledgerFile)) {
         const gate = await readJson(ledgerFile);
+        if (gate.status === 'waiting_for_human' && entry.subdir === 'inbox') {
+          const inboxFile = path.join(queueSubdirFor(root, queue, 'inbox'), `${safeTaskId(taskId)}.json`);
+          if (await exists(inboxFile)) {
+            const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(inboxFile));
+            await writeJson(waitingFile, {
+              ...entry.task,
+              status: 'waiting_for_human',
+              waitingGateId: gateId,
+              waitingSince: gate.requested_at ?? new Date().toISOString()
+            });
+            await rm(inboxFile, { force: true });
+          }
+        }
         results.push({ taskId, checkpointId, gateId, outcome: gate.status === 'resolved' ? 'resolved' : 'already_notified', ledger: path.relative(root, ledgerFile) });
         continue;
       }
@@ -1831,6 +1880,19 @@ export async function notifyHumanInputRequests(root, options = {}) {
         requested_at: new Date().toISOString(),
         notification: compactCommandResult(result)
       });
+      if (entry.subdir === 'inbox') {
+        const inboxFile = path.join(queueSubdirFor(root, queue, 'inbox'), `${safeTaskId(taskId)}.json`);
+        if (await exists(inboxFile)) {
+          const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(inboxFile));
+          await writeJson(waitingFile, {
+            ...entry.task,
+            status: 'waiting_for_human',
+            waitingGateId: gateId,
+            waitingSince: new Date().toISOString()
+          });
+          await rm(inboxFile, { force: true });
+        }
+      }
       results.push({ taskId, checkpointId, gateId, outcome: 'sent', ledger: path.relative(root, ledgerFile) });
     }
   }
@@ -1856,37 +1918,153 @@ export async function resolveHumanInput(root, options = {}) {
   const ledgerFile = path.join(queueDirFor(root, queue), 'human-input', 'gates', `${safeTaskId(taskId)}.${checkpointId}.json`);
   if (!await exists(ledgerFile)) throw new Error(`Human-input gate not found: ${options.gateId}`);
   const gate = await readJson(ledgerFile);
-  if (gate.status === 'resolved') return { gate, outcome: 'already_resolved', ledger: path.relative(root, ledgerFile) };
+  if (['resolved', 'consumed', 'satisfied'].includes(gate.status)) return { gate, outcome: 'already_resolved', ledger: path.relative(root, ledgerFile) };
+  const receivedAt = new Date().toISOString();
+  const response = options.input.trim();
+  const secretDir = path.join(queueDirFor(root, queue), 'human-input', 'secrets');
+  const eventsDir = path.join(queueDirFor(root, queue), 'human-input', 'events');
+  await mkdir(secretDir, { recursive: true, mode: 0o700 });
+  await mkdir(eventsDir, { recursive: true });
+  const secretFile = path.join(secretDir, `${safeTaskId(taskId)}.${checkpointId}.${isoStamp()}.secret`);
+  const handle = await open(secretFile, 'wx', 0o600);
+  try {
+    await handle.writeFile(response);
+  } finally {
+    await handle.close();
+  }
+  const responseSha256 = createHash('sha256').update(response).digest('hex');
   const resolved = {
     ...gate,
     status: 'resolved',
-    response: options.input.trim(),
+    secret_received: true,
+    response_sha256: responseSha256,
+    response_ref: path.relative(root, secretFile),
     response_message_id: options.sourceMessageId ?? null,
-    resolved_at: new Date().toISOString()
+    resolved_at: receivedAt
   };
+  delete resolved.response;
   await writeJson(ledgerFile, resolved);
-  const found = await findTaskFile(root, queue, taskId, ['failed', 'canceled']);
+  const eventFile = path.join(eventsDir, `${safeTaskId(taskId)}.${checkpointId}.${isoStamp()}.json`);
+  await writeJson(eventFile, {
+    version: 1,
+    type: 'human_input_resolved',
+    gate_id: options.gateId,
+    task_id: taskId,
+    checkpoint_id: checkpointId,
+    status: 'pending_consumption',
+    secret_received: true,
+    response_sha256: responseSha256,
+    response_ref: path.relative(root, secretFile),
+    response_message_id: options.sourceMessageId ?? null,
+    created_at: receivedAt
+  });
+  const found = await findTaskFile(root, queue, taskId, ['inbox', 'active', 'waiting', 'failed', 'canceled']);
   let requeued = null;
+  let updated = null;
   if (found) {
     const task = await readJson(found.file);
-    const inboxFile = path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(found.file));
-    await writeJson(inboxFile, {
+    const taskUpdate = {
       ...task,
-      status: 'queued',
-      body: `${task.body}\n\nHuman input for gate ${options.gateId}:\n${options.input.trim()}`,
       humanInput: {
         gate_id: options.gateId,
         checkpoint_id: checkpointId,
-        response: options.input.trim(),
-        received_at: resolved.resolved_at
-      },
-      requeuedAt: resolved.resolved_at,
-      requeuedFrom: found.subdir
+        secret_received: true,
+        response_sha256: responseSha256,
+        event: path.relative(root, eventFile),
+        received_at: receivedAt
+      }
+    };
+    if (['waiting', 'failed', 'canceled'].includes(found.subdir)) {
+      const inboxFile = path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(found.file));
+      await writeJson(inboxFile, {
+        ...taskUpdate,
+        status: 'queued',
+        requeuedAt: receivedAt,
+        requeuedFrom: found.subdir
+      });
+      await rm(found.file, { force: true });
+      requeued = path.relative(root, inboxFile);
+    } else if (found.subdir === 'inbox') {
+      await writeJson(found.file, taskUpdate);
+      updated = path.relative(root, found.file);
+    } else {
+      // An active dispatcher cannot be mutated safely. The durable event is
+      // consumed on the next bounded tick after the active run finishes.
+      updated = path.relative(root, eventFile);
+    }
+  }
+  return {
+    gate: resolved,
+    outcome: requeued ? 'resolved_and_requeued' : found?.subdir === 'active' ? 'resolved_pending_safe_boundary' : 'resolved_for_next_tick',
+    requeued,
+    updated,
+    event: path.relative(root, eventFile)
+  };
+}
+
+async function prepareHumanInputContext(root, queue, taskId) {
+  const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
+  const runtimeDir = taskRuntimeDirFor(root, queue, taskId);
+  const contextFile = path.join(runtimeDir, 'human_input_context.json');
+  const gates = [];
+  for (const file of await listJson(gatesDir)) {
+    const full = path.join(gatesDir, file);
+    const gate = await readJson(full);
+    if (gate.task_id !== taskId || !['resolved', 'consumed'].includes(gate.status)) continue;
+    const consumedAt = gate.consumed_at ?? new Date().toISOString();
+    const consumed = gate.status === 'resolved' ? { ...gate, status: 'consumed', consumed_at: consumedAt } : gate;
+    if (gate.status === 'resolved') await writeJson(full, consumed);
+    gates.push({
+      gate_id: consumed.gate_id,
+      checkpoint_id: consumed.checkpoint_id,
+      status: consumed.status,
+      secret_received: Boolean(consumed.secret_received),
+      response_sha256: consumed.response_sha256 ?? null,
+      response_ref: consumed.response_ref ? path.join(root, consumed.response_ref) : null,
+      resolved_at: consumed.resolved_at ?? null,
+      consumed_at: consumed.consumed_at ?? null
+    });
+  }
+  await writeJson(contextFile, { version: 1, task_id: taskId, gates });
+  return contextFile;
+}
+
+async function destroyConsumedHumanInputSecrets(root, queue, taskId) {
+  const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
+  for (const file of await listJson(gatesDir)) {
+    const full = path.join(gatesDir, file);
+    const gate = await readJson(full);
+    if (gate.task_id !== taskId || gate.status !== 'consumed' || !gate.response_ref) continue;
+    await rm(path.join(root, gate.response_ref), { force: true });
+    await writeJson(full, {
+      ...gate,
+      secret_destroyed: true,
+      secret_destroyed_at: new Date().toISOString()
+    });
+  }
+}
+
+async function reconcileHumanInputGates(root, queue, taskId) {
+  const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
+  const checkpointsDir = path.join(taskRuntimeDirFor(root, queue, taskId), 'checkpoints');
+  const checkpoints = [];
+  for (const file of await listJson(checkpointsDir)) checkpoints.push(await readJson(path.join(checkpointsDir, file)));
+  for (const file of await listJson(gatesDir)) {
+    const full = path.join(gatesDir, file);
+    const gate = await readJson(full);
+    if (gate.task_id !== taskId || gate.status !== 'consumed') continue;
+    const successor = checkpoints
+      .filter((checkpoint) => checkpoint?.revises_checkpoint_id === gate.checkpoint_id)
+      .sort((a, b) => Number(b.sequence ?? 0) - Number(a.sequence ?? 0))[0];
+    if (!successor) continue;
+    await writeJson(full, {
+      ...gate,
+      status: 'satisfied',
+      satisfied_at: new Date().toISOString(),
+      satisfied_by_checkpoint_id: successor.checkpoint_id,
+      successor_status: successor.status ?? null
     });
-    await rm(found.file, { force: true });
-    requeued = path.relative(root, inboxFile);
   }
-  return { gate: resolved, outcome: requeued ? 'resolved_and_requeued' : 'resolved_pending_terminal', requeued };
 }
 
 export function taskRuntimeDirFor(root, queue, taskId) {
@@ -2017,6 +2195,10 @@ function buildTaskContract(queue, task, options = {}) {
   const inferredRisk = inferTaskRisk(task);
   const modelAssessed = task.riskAssessment === 'model_assessed';
   const riskLevel = options.riskLevel ?? (modelAssessed ? 'model_assessed' : inferredRisk.level);
+  const requestText = `${task.title ?? ''}\n${task.body ?? ''}`.toLowerCase();
+  const taskScope = /project[-_ ]level|项目级|完整项目|整体项目|single milestone|单(?:一)?里程碑/.test(requestText)
+    ? 'project'
+    : 'scoped_task';
   return {
     version: 1,
     task_id: task.id,
@@ -2024,6 +2206,7 @@ function buildTaskContract(queue, task, options = {}) {
     title: task.title,
     original_request: task.body,
     goal: task.body,
+    task_scope: taskScope,
     deliverables: [
       'Structured run artifact',
       'Concise completion summary',
@@ -2362,11 +2545,15 @@ function buildDevPlan(contract, acceptancePlan) {
       version: 1,
       task_id: contract.task_id,
       checkpoint_id: firstCheckpointId,
+      milestone_id: firstCheckpointId,
+      revises_checkpoint_id: null,
       status: 'ready_for_acceptance | blocked | needs_human_input',
       summary: 'What changed and why.',
       files_changed: [],
       verification: [],
       blockers: [],
+      deferred_gates: [],
+      project_completion: null,
       risks: [],
       next_action: 'acceptance_review'
     },
@@ -2655,6 +2842,11 @@ export async function writeAcceptanceReviews(root, queue, task, taskContract, ac
     await writeJson(reviewFile, review);
     reviews.push({
       checkpointId: review.checkpoint_id,
+      milestoneId: checkpoint.milestone_id ?? null,
+      revisesCheckpointId: checkpoint.revises_checkpoint_id ?? null,
+      sequence: Number(checkpoint.sequence ?? String(checkpoint.checkpoint_id ?? '').match(/(\d+)$/)?.[1] ?? 0),
+      createdAt: checkpoint.created_at ?? review.created_at,
+      projectCompletion: checkpoint.project_completion ?? null,
       status: review.status,
       file: path.relative(root, reviewFile)
     });
@@ -2672,16 +2864,55 @@ export async function writeAcceptanceReviews(root, queue, task, taskContract, ac
   };
 }
 
-function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoints, acceptanceReviews, context = {}) {
+function compareReviewSequence(a, b) {
+  const sequenceDelta = Number(a.sequence ?? 0) - Number(b.sequence ?? 0);
+  if (sequenceDelta !== 0) return sequenceDelta;
+  return String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? ''));
+}
+
+function compareReviewRecency(a, b) {
+  const createdDelta = String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? ''));
+  if (createdDelta !== 0 && a.createdAt && b.createdAt) return createdDelta;
+  const aCheckpoint = Number(String(a.checkpointId ?? '').match(/(\d+)$/)?.[1] ?? 0);
+  const bCheckpoint = Number(String(b.checkpointId ?? '').match(/(\d+)$/)?.[1] ?? 0);
+  if (aCheckpoint !== bCheckpoint) return aCheckpoint - bCheckpoint;
+  return compareReviewSequence(a, b);
+}
+
+export function selectEffectiveAcceptanceReviews(devPlan, acceptanceReviews) {
+  const allReviews = acceptanceReviews?.reviews ?? [];
+  const planned = Array.isArray(devPlan?.checkpoints) ? devPlan.checkpoints : [];
+  if (planned.length <= 1) {
+    return [...allReviews].sort(compareReviewRecency).slice(-1);
+  }
+  const selected = [];
+  for (const checkpoint of planned) {
+    const milestoneId = checkpoint.id;
+    const candidates = allReviews.filter((review) =>
+      review.milestoneId === milestoneId || review.checkpointId === milestoneId
+    );
+    if (candidates.length === 0) continue;
+    selected.push([...candidates].sort(compareReviewSequence).at(-1));
+  }
+  return selected;
+}
+
+export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoints, acceptanceReviews, context = {}) {
   const reasons = [];
   const nextActions = [];
   const requiredCheckpoints = Array.isArray(devPlan?.checkpoints) ? devPlan.checkpoints.length : 0;
   const checkpointCount = checkpoints?.count ?? 0;
-  const reviewCount = acceptanceReviews?.count ?? 0;
-  const acceptedCount = acceptanceReviews?.accepted ?? 0;
-  const reviseCount = acceptanceReviews?.revise ?? 0;
-  const blockedCount = acceptanceReviews?.blocked ?? 0;
+  const allReviews = acceptanceReviews?.reviews ?? [];
+  // Checkpoints produced after the planned set are revision/progress snapshots,
+  // not additional required milestones. Judge the latest complete set so a
+  // resolved historical blocker does not permanently poison the task.
+  const effectiveReviews = selectEffectiveAcceptanceReviews(devPlan, acceptanceReviews);
+  const reviewCount = effectiveReviews.length;
+  const acceptedCount = effectiveReviews.filter((item) => item.status === 'accepted').length;
+  const reviseCount = effectiveReviews.filter((item) => item.status === 'revise').length;
+  const blockedCount = effectiveReviews.filter((item) => item.status === 'blocked').length;
   const dispatchStatus = context.dispatchStatus ?? 'unknown';
+  const projectCompletionAccepted = effectiveReviews.some((review) => review.projectCompletion?.status === 'accepted');
   let outcome = 'needs_revision';
 
   if (dispatchStatus === 'blocked_preflight') {
@@ -2724,6 +2955,10 @@ function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoints, acc
     outcome = 'needs_revision';
     reasons.push(`Accepted checkpoints (${acceptedCount}) do not cover required checkpoints (${Math.max(requiredCheckpoints, 1)}).`);
     nextActions.push('Complete and review the remaining planned checkpoints.');
+  } else if (contract.task_scope === 'project' && !projectCompletionAccepted) {
+    outcome = 'project_in_progress';
+    reasons.push('The latest milestone is accepted, but the project terminal contract is not accepted.');
+    nextActions.push('Continue with the next safe actionable project backlog item.');
   } else if (contract.requires_human_gate) {
     outcome = 'ready_for_human_review';
     reasons.push('All reviewed checkpoints are accepted, and the task contract requires a human gate.');
@@ -2755,6 +2990,8 @@ function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoints, acc
       planned_checkpoints: requiredCheckpoints,
       produced_checkpoints: checkpointCount,
       reviews: reviewCount,
+      historical_reviews: allReviews.length,
+      effective_review_ids: effectiveReviews.map((review) => review.checkpointId),
       accepted: acceptedCount,
       revise: reviseCount,
       blocked: blockedCount,
@@ -2792,7 +3029,9 @@ function queueStatusFromFinalJudgement(currentStatus, finalJudgement) {
   if (!finalJudgement?.judgement) return currentStatus;
   if (currentStatus !== 'completed') return currentStatus;
   const outcome = finalJudgement.judgement.outcome;
-  if (outcome === 'ready_for_human_review' || outcome === 'ready_to_apply') return currentStatus;
+  if (outcome === 'ready_to_apply') return currentStatus;
+  if (outcome === 'project_in_progress') return outcome;
+  if (outcome === 'ready_for_human_review') return outcome;
   return outcome;
 }
 
@@ -2928,6 +3167,7 @@ export async function queueStatus(root, queue) {
     queue,
     queued: (await listJson(queueSubdirFor(root, queue, 'inbox'))).length,
     active: activeFiles.length,
+    waiting: (await listJson(queueSubdirFor(root, queue, 'waiting'))).length,
     done: (await listJson(queueSubdirFor(root, queue, 'done'))).length,
     failed: (await listJson(queueSubdirFor(root, queue, 'failed'))).length,
     canceled: (await listJson(queueSubdirFor(root, queue, 'canceled'))).length,
@@ -3544,7 +3784,7 @@ async function nextQueuedTaskFile(root, queue) {
   return path.join(queueSubdirFor(root, queue, 'inbox'), files[0]);
 }
 
-async function findTaskFile(root, queue, taskId, subdirs = ['inbox', 'active', 'failed', 'done', 'canceled']) {
+async function findTaskFile(root, queue, taskId, subdirs = ['inbox', 'active', 'waiting', 'failed', 'done', 'canceled']) {
   const wanted = taskId.endsWith('.json') ? taskId : `${taskId}.json`;
   for (const subdir of subdirs) {
     const file = path.join(queueSubdirFor(root, queue, subdir), wanted);
@@ -4069,6 +4309,27 @@ export async function queueHumanDecision(root, queue, taskId, options = {}) {
   };
   await writeJson(file, artifact);
 
+  let transitionedTask = null;
+  if (decision === 'approve' && found.subdir !== 'done') {
+    const completedAt = artifact.created_at;
+    transitionedTask = {
+      ...task,
+      status: 'completed',
+      humanApprovedAt: completedAt,
+      humanReviewDecision: path.relative(root, file)
+    };
+    const completedFile = path.join(queueSubdirFor(root, normalized, 'done'), path.basename(found.file));
+    await writeJson(completedFile, transitionedTask);
+    await rm(found.file, { force: true });
+    artifact.effects.queueTransition = {
+      from: found.subdir,
+      to: 'done',
+      status: 'completed',
+      file: path.relative(root, completedFile)
+    };
+    await writeJson(file, artifact);
+  }
+
   let revisionRequest = null;
   if (decision === 'request_changes') {
     const revisionFile = path.join(dir, 'human_revision_request.json');
@@ -4098,6 +4359,7 @@ export async function queueHumanDecision(root, queue, taskId, options = {}) {
     decisionFile: path.relative(root, file),
     revisionRequestFile: revisionRequest?.path ?? null,
     revisionNext,
+    transitionedTask,
     artifact
   };
 }
@@ -4489,7 +4751,7 @@ export async function queueRevisionReview(root, queue, options = {}) {
   };
 }
 
-const TASK_STATE_DIRS = ['inbox', 'active', 'failed', 'done', 'canceled'];
+const TASK_STATE_DIRS = ['inbox', 'active', 'waiting', 'failed', 'done', 'canceled'];
 
 async function listQueueTasks(root, queue) {
   const tasks = [];
@@ -7484,6 +7746,37 @@ async function recoverStaleActive(root, queue, staleActiveMs) {
   return recovered;
 }
 
+async function recoverOrphanActive(root, queue) {
+  const activeDir = queueSubdirFor(root, queue, 'active');
+  const inboxDir = queueSubdirFor(root, queue, 'inbox');
+  const files = await listJson(activeDir);
+  const recovered = [];
+  for (const file of files) {
+    const activeFile = path.join(activeDir, file);
+    const task = await readJson(activeFile);
+    const recoveredAt = new Date().toISOString();
+    const inboxFile = path.join(inboxDir, file);
+    // Move first so a crash cannot leave duplicate active/inbox copies.
+    await rename(activeFile, inboxFile);
+    await writeJson(inboxFile, {
+      ...task,
+      status: 'queued',
+      orphanRecoveredAt: recoveredAt,
+      orphanRecoveryCount: (task.orphanRecoveryCount ?? 0) + 1,
+      requeuedAt: recoveredAt,
+      requeuedFrom: 'active',
+      recoveryReason: 'queue_lock_reacquired_with_active_task'
+    });
+    recovered.push({
+      taskId: task.id,
+      from: path.relative(root, activeFile),
+      file: path.relative(root, inboxFile),
+      recoveredAt
+    });
+  }
+  return recovered;
+}
+
 function compactCommandResult(result) {
   return {
     exitCode: result.exitCode,
@@ -7846,6 +8139,18 @@ export async function runQueueOnce(root, options) {
   }
 
   try {
+    // Holding this newly acquired lock proves no previous runner owns a valid
+    // queue lease. Any task left in active/ is therefore an orphan from an
+    // interrupted parent runner. Requeue it immediately so existing
+    // checkpoints can be reviewed and execution can resume in this tick.
+    const orphanRecovered = await recoverOrphanActive(root, queue);
+    if (orphanRecovered.length > 0) {
+      progress.emit('queue', 'orphan_recovered', `Recovered ${orphanRecovered.length} orphan active task(s)`, {
+        queue,
+        count: orphanRecovered.length,
+        tasks: orphanRecovered.map((entry) => entry.taskId)
+      });
+    }
     const staleRecovered = await recoverStaleActive(root, queue, options.staleActiveMs);
     if (staleRecovered.length > 0) {
       progress.emit('queue', 'recovered', `Recovered ${staleRecovered.length} stale active task(s)`, {
@@ -7864,6 +8169,7 @@ export async function runQueueOnce(root, options) {
         status: 'empty',
         exitCode: 0,
         staleRecovered,
+        orphanRecovered,
         progress: progress.events
       };
     }
@@ -7901,7 +8207,11 @@ export async function runQueueOnce(root, options) {
     let revisionRequest = null;
 
     try {
-      taskContract = await writeTaskContract(root, queue, task);
+      taskContract = await writeTaskContract(root, queue, task, {
+        riskLevel: options.riskLevel,
+        riskReasons: options.riskReasons,
+        requiresHumanGate: options.requiresHumanGate
+      });
       progress.emit('planning', 'task_contract', `Wrote task contract (${taskContract.contract.risk_level})`, {
         taskId: task.id,
         artifact: taskContract.file,
@@ -7950,8 +8260,13 @@ export async function runQueueOnce(root, options) {
         finalStatus = 'blocked_preflight';
         exitCode = 2;
       } else {
+        const humanInputContextFile = await prepareHumanInputContext(root, queue, task.id);
         const runContext = {
-          env: taskPlanningEnv(root, taskContract, acceptancePlan, devPlan),
+          env: {
+            ...taskPlanningEnv(root, taskContract, acceptancePlan, devPlan),
+            LOOP_HUMAN_INPUT_CONTEXT_FILE: humanInputContextFile,
+            LOOP_HUMAN_INPUT_CONTEXT_FILE_REL: path.relative(root, humanInputContextFile)
+          },
           progress
         };
         if (finalStatus === 'unknown' && worktreeEnabled(options)) {
@@ -7988,6 +8303,7 @@ export async function runQueueOnce(root, options) {
         if (finalStatus === 'unknown') {
           dispatchAttempts = await runDispatchWithRetry(root, options, queue, task, activeFile, runId, timeoutMs, runContext);
           dispatch = dispatchAttempts[dispatchAttempts.length - 1]?.result ?? null;
+          await destroyConsumedHumanInputSecrets(root, queue, task.id);
           const dispatchClassification = dispatchAttempts[dispatchAttempts.length - 1]?.failureClassification ?? null;
           if (dispatch?.canceled) {
             finalStatus = 'superseded';
@@ -8010,6 +8326,7 @@ export async function runQueueOnce(root, options) {
         }
       }
       checkpoints = await checkpointSummary(root, devPlan);
+      await reconcileHumanInputGates(root, queue, task.id);
       progress.emit('acceptance', 'checkpoint_summary', `Collected ${checkpoints.count} checkpoint(s)`, {
         taskId: task.id,
         count: checkpoints.count,
@@ -8088,26 +8405,32 @@ export async function runQueueOnce(root, options) {
       revisionRequest = await writeRevisionRequest(root, queue, task, taskContract, acceptancePlan, devPlan, finalJudgement, acceptanceReviews);
     }
 
-    destination = finalStatus === 'completed'
+    destination = finalStatus === 'project_in_progress'
+      ? queueSubdirFor(root, queue, 'inbox')
+      : finalStatus === 'completed'
       ? queueSubdirFor(root, queue, 'done')
       : finalStatus === 'superseded' ? queueSubdirFor(root, queue, 'canceled')
       : queueSubdirFor(root, queue, 'failed');
-    exitCode = ['completed', 'superseded'].includes(finalStatus) ? 0 : 1;
+    exitCode = ['completed', 'superseded', 'project_in_progress'].includes(finalStatus) ? 0 : 1;
 
     const finishedAt = new Date().toISOString();
-    progress.emit('queue', finalStatus === 'completed' ? 'completed' : 'needs_attention', `Task finished with status ${finalStatus}`, {
+    progress.emit('queue', finalStatus === 'completed' ? 'completed' : finalStatus === 'project_in_progress' ? 'continued' : 'needs_attention', `Task finished with status ${finalStatus}`, {
       queue,
       taskId: task.id,
       status: finalStatus
     });
     const completedTask = {
       ...task,
-      status: finalStatus,
+      status: finalStatus === 'project_in_progress' ? 'queued' : finalStatus,
       startedAt,
       finishedAt,
       attempts: (task.attempts ?? 0) + Math.max(dispatchAttempts.length, dispatch ? 1 : 0),
       runPath: path.relative(root, runPath)
     };
+    if (finalStatus === 'project_in_progress') {
+      completedTask.projectContinuedAt = finishedAt;
+      completedTask.projectContinuationCount = (task.projectContinuationCount ?? 0) + 1;
+    }
     const completedFile = path.join(destination, path.basename(activeFile));
     await writeJson(completedFile, completedTask);
     await rm(activeFile, { force: true });
@@ -8181,6 +8504,7 @@ export async function runQueueOnce(root, options) {
       } : null,
       verification,
       staleRecovered,
+      orphanRecovered,
       progress: progress.events,
       taskPath: path.relative(root, completedFile),
       runPath: path.relative(root, runPath)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -16,7 +16,7 @@
   "scripts": {
     "check:config-drift": "node --check scripts/config-drift-self-test.mjs && node scripts/config-drift-self-test.mjs",
     "check:openclaw-install": "node --check scripts/openclaw-install.mjs && node --check scripts/openclaw-doctor.mjs && node --check scripts/openclaw-smoke.mjs && node --check scripts/openclaw-manage.mjs && node scripts/openclaw-install-self-test.mjs",
-    "check": "npm run check:config-drift && npm run check:openclaw-install && node --check bin/loop-engineering.mjs && node --check lib/core.mjs && node scripts/route-notify-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
+    "check": "npm run check:config-drift && npm run check:openclaw-install && node --check bin/loop-engineering.mjs && node --check lib/core.mjs && node scripts/final-judgement-self-test.mjs && node scripts/route-notify-self-test.mjs && node scripts/scheduler-heartbeat-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
     "pack:dry": "npm pack --dry-run"
   },
   "engines": {

package/scripts/final-judgement-self-test.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { buildFinalJudgement, selectEffectiveAcceptanceReviews } from '../lib/core.mjs';
+
+const basePlan = { rubric: [], automation: [] };
+const baseContract = { task_id: 't1', risk_level: 'L1', requires_human_gate: false, task_scope: 'scoped_task' };
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = {
+    reviews: [
+      { checkpointId: 'cp1', sequence: 1, status: 'blocked' },
+      { checkpointId: 'cp2', sequence: 2, status: 'accepted' },
+      { checkpointId: 'cp10', sequence: 10, status: 'accepted' }
+    ]
+  };
+  assert.equal(selectEffectiveAcceptanceReviews(devPlan, reviews)[0].checkpointId, 'cp10');
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = {
+    reviews: [
+      { checkpointId: 'cp5', milestoneId: 'G-01-retry', sequence: 5, createdAt: '2026-08-07T04:00:00.000Z', status: 'accepted' },
+      { checkpointId: 'cp14', milestoneId: 'G-01-auth', sequence: 3, createdAt: '2026-08-07T12:00:00.000Z', status: 'blocked' }
+    ]
+  };
+  assert.equal(selectEffectiveAcceptanceReviews(devPlan, reviews)[0].checkpointId, 'cp14');
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'design' }, { id: 'verify' }] };
+  const reviews = {
+    reviews: [
+      { checkpointId: 'design', milestoneId: 'design', sequence: 1, status: 'accepted' },
+      { checkpointId: 'verify-v1', milestoneId: 'verify', sequence: 2, status: 'blocked' },
+      { checkpointId: 'verify-v2', milestoneId: 'verify', sequence: 3, status: 'accepted' }
+    ]
+  };
+  assert.deepEqual(selectEffectiveAcceptanceReviews(devPlan, reviews).map((review) => review.checkpointId), ['design', 'verify-v2']);
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{ checkpointId: 'cp5', sequence: 5, status: 'accepted', projectCompletion: { status: 'in_progress' } }] };
+  const judgement = buildFinalJudgement(
+    { ...baseContract, task_scope: 'project' },
+    basePlan,
+    devPlan,
+    { count: 5 },
+    reviews,
+    { dispatchStatus: 'completed' }
+  );
+  assert.equal(judgement.outcome, 'project_in_progress');
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{ checkpointId: 'cp6', sequence: 6, status: 'accepted', projectCompletion: { status: 'accepted' } }] };
+  const judgement = buildFinalJudgement(
+    { ...baseContract, task_scope: 'project' },
+    basePlan,
+    devPlan,
+    { count: 6 },
+    reviews,
+    { dispatchStatus: 'completed' }
+  );
+  assert.equal(judgement.outcome, 'ready_to_apply');
+}
+
+console.log('final judgement self-test passed');

package/scripts/route-notify-self-test.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import assert from 'node:assert/strict';
-import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { mkdtemp, readdir, rename, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import {
@@ -10,6 +10,8 @@ import {
   normalizeGoalDecision,
   notifyHumanInputRequests,
   notifyTerminalTasks,
+  queueHumanDecision,
+  queueStatus,
   queueSubdirFor,
   readJson,
   routeLoopMessage,
@@ -76,6 +78,97 @@ const contract = await readJson(path.join(taskRuntimeDirFor(root, queue, routed.
 assert.equal(contract.risk_level, 'model_assessed');
 assert.equal(contract.requires_human_gate, false);
 
+const orphanQueue = 'orphan-recovery-smoke';
+const orphanRouted = await routeLoopMessage(root, {
+  route: true,
+  confirmExecute: true,
+  queue: orphanQueue,
+  message: '走 loop 验证异常退出自动恢复',
+  sourceChannel: 'feishu',
+  sourceTarget: 'user-1'
+});
+const orphanName = `${orphanRouted.task.id}.json`;
+const orphanInbox = path.join(queueSubdirFor(root, orphanQueue, 'inbox'), orphanName);
+const orphanActive = path.join(queueSubdirFor(root, orphanQueue, 'active'), orphanName);
+await writeJson(orphanActive, { ...(await readJson(orphanInbox)), status: 'active', startedAt: new Date().toISOString() });
+await rm(orphanInbox, { force: true });
+await writeJson(path.join(taskRuntimeDirFor(root, orphanQueue, orphanRouted.task.id), 'checkpoints', 'cp-before-crash.json'), {
+  version: 1,
+  task_id: orphanRouted.task.id,
+  checkpoint_id: 'cp-before-crash',
+  status: 'in_progress',
+  summary: 'Durable progress written before the parent runner exited.',
+  files_changed: [],
+  verification: [],
+  blockers: [],
+  risks: [],
+  next_action: 'resume_from_checkpoint'
+});
+const orphanRun = await runQueueOnce(root, {
+  queue: orphanQueue,
+  dispatcher: '/bin/true',
+  timeoutMs: 10_000,
+  leaseMs: 20_000,
+  staleActiveMs: 60_000
+});
+assert.equal(orphanRun.processed, true);
+assert.equal(orphanRun.run.orphanRecovered.length, 1);
+assert.equal(orphanRun.run.orphanRecovered[0].taskId, orphanRouted.task.id);
+assert.ok(orphanRun.progress.some((event) => event.status === 'orphan_recovered'));
+const orphanTerminal = await readJson(path.join(root, orphanRun.taskPath));
+assert.equal(orphanTerminal.orphanRecoveryCount, 1);
+assert.equal(orphanTerminal.requeuedFrom, 'active');
+assert.equal((await readJson(path.join(taskRuntimeDirFor(root, orphanQueue, orphanRouted.task.id), 'checkpoints', 'cp-before-crash.json'))).checkpoint_id, 'cp-before-crash');
+
+const reviewQueue = 'human-review-smoke';
+const reviewTask = await routeLoopMessage(root, {
+  route: true,
+  confirmExecute: true,
+  queue: reviewQueue,
+  message: '走 loop 生成需要人工验收的交付物',
+  sourceChannel: 'feishu',
+  sourceTarget: 'user-1'
+});
+let reviewCheckpointWrite = null;
+const reviewRun = await runQueueOnce(root, {
+  queue: reviewQueue,
+  dispatcher: '/bin/sleep 0.1',
+  requiresHumanGate: true,
+  timeoutMs: 10_000,
+  leaseMs: 20_000,
+  staleActiveMs: 60_000,
+  onProgress: (event) => {
+    if (event.phase !== 'dispatch' || event.status !== 'running' || reviewCheckpointWrite) return;
+    reviewCheckpointWrite = writeJson(path.join(taskRuntimeDirFor(root, reviewQueue, reviewTask.task.id), 'checkpoints', 'cp-review.json'), {
+      version: 1,
+      task_id: reviewTask.task.id,
+      checkpoint_id: 'cp-review',
+      status: 'ready_for_acceptance',
+      summary: 'The deliverable is complete and explicitly awaits human acceptance.',
+      files_changed: [],
+      verification: [{ command: '/bin/true', outcome: 'passed' }],
+      blockers: [],
+      risks: [],
+      next_action: 'human_acceptance'
+    });
+  }
+});
+await reviewCheckpointWrite;
+assert.equal(reviewRun.status, 'ready_for_human_review');
+assert.match(reviewRun.taskPath, /failed/);
+const reviewStatus = await queueStatus(root, reviewQueue);
+assert.equal(reviewStatus.done, 0);
+assert.equal(reviewStatus.failed, 1);
+const reviewNotice = await notifyTerminalTasks(root, { queue: reviewQueue, dryRun: true });
+assert.equal(reviewNotice.results[0].outcome, 'dry_run');
+assert.match(reviewNotice.results[0].message, /ready for human acceptance/);
+assert.match(reviewNotice.results[0].message, /approve, request_changes, or reject/);
+const reviewDecision = await queueHumanDecision(root, reviewQueue, reviewTask.task.id, { decision: 'approve' });
+assert.equal(reviewDecision.transitionedTask.status, 'completed');
+const approvedStatus = await queueStatus(root, reviewQueue);
+assert.equal(approvedStatus.done, 1);
+assert.equal(approvedStatus.failed, 0);
+
 for (const suffix of ['second', 'third']) {
   await routeLoopMessage(root, {
     route: true,
@@ -281,10 +374,45 @@ const gateId = gateSent.results[0].gateId;
 const resolved = await resolveHumanInput(root, { queue, gateId, input: '123456', sourceMessageId: 'reply-1' });
 assert.equal(resolved.outcome, 'resolved_and_requeued');
 const requeuedTask = await readJson(path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(failedFile)));
-assert.equal(requeuedTask.humanInput.response, '123456');
-assert.match(requeuedTask.body, /Human input for gate/);
+assert.equal(requeuedTask.humanInput.secret_received, true);
+assert.equal(requeuedTask.body.includes('123456'), false);
+const resolvedGate = await readJson(path.join(root, resolved.ledger ?? gateSent.results[0].ledger));
+assert.equal(JSON.stringify(resolvedGate).includes('123456'), false);
+assert.equal(resolvedGate.response_sha256.length, 64);
+
+// Queued tasks receive a non-sensitive event reference without being moved.
+const queuedCheckpoint = path.join(taskRuntimeDirFor(root, queue, routed.task.id), 'checkpoints', 'cp-queued.json');
+await writeJson(queuedCheckpoint, {
+  version: 1, task_id: routed.task.id, checkpoint_id: 'cp-queued', status: 'needs_human_input',
+  blockers: ['Provide queued input.'], verification: [], risks: [], next_action: 'wait'
+});
+await notifyHumanInputRequests(root, { queue, notifyCommand: '/bin/true' });
+const queuedGateId = `${routed.task.id}:cp-queued`;
+const waitingTaskFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(failedFile));
+assert.equal((await readJson(waitingTaskFile)).status, 'waiting_for_human');
+const queuedResolved = await resolveHumanInput(root, { queue, gateId: queuedGateId, input: 'queued-secret' });
+assert.equal(queuedResolved.outcome, 'resolved_and_requeued');
+const queuedAfterInput = await readJson(path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(failedFile)));
+assert.equal(queuedAfterInput.status, 'queued');
+assert.equal(JSON.stringify(queuedAfterInput).includes('queued-secret'), false);
+
+// Active tasks are not mutated; their event is consumed at the next safe tick.
+const inboxRequeued = path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(failedFile));
+const activeRequeued = path.join(queueSubdirFor(root, queue, 'active'), path.basename(failedFile));
+await rename(inboxRequeued, activeRequeued);
+const activeBefore = await readJson(activeRequeued);
+const activeCheckpoint = path.join(taskRuntimeDirFor(root, queue, routed.task.id), 'checkpoints', 'cp-active.json');
+await writeJson(activeCheckpoint, {
+  version: 1, task_id: routed.task.id, checkpoint_id: 'cp-active', status: 'needs_human_input',
+  blockers: ['Provide active input.'], verification: [], risks: [], next_action: 'wait'
+});
+await notifyHumanInputRequests(root, { queue, notifyCommand: '/bin/true' });
+const activeResolved = await resolveHumanInput(root, { queue, gateId: `${routed.task.id}:cp-active`, input: 'active-secret' });
+assert.equal(activeResolved.outcome, 'resolved_pending_safe_boundary');
+assert.deepEqual(await readJson(activeRequeued), activeBefore);
+await rename(activeRequeued, inboxRequeued);
 await writeJson(failedFile, { ...requeuedTask, status: 'needs_human_input' });
-await rm(path.join(queueSubdirFor(root, queue, 'inbox'), path.basename(failedFile)), { force: true });
+await rm(inboxRequeued, { force: true });
 
 const dryRun = await notifyTerminalTasks(root, { queue, dryRun: true });
 assert.equal(dryRun.results[0].outcome, 'dry_run');

package/scripts/scheduler-heartbeat-self-test.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  doctorReport,
+  enqueueTask,
+  queueSchedulerTick,
+  writeJson
+} from '../lib/core.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-scheduler-heartbeat-'));
+const queue = 'required-scheduler';
+await mkdir(path.join(root, 'configs', 'loops', 'queues'), { recursive: true });
+await writeJson(path.join(root, 'configs', 'loops', 'queues', `${queue}.json`), {
+  queue,
+  dispatcher: '/bin/true',
+  scheduler: {
+    required: true,
+    heartbeatMaxAge: '5m',
+    initialInterval: '1m',
+    minInterval: '1m',
+    maxInterval: '4h'
+  }
+});
+await enqueueTask(root, { queue, title: 'heartbeat smoke', task: 'remain queued' });
+
+const missing = await doctorReport(root);
+const missingCheck = missing.checks.find((check) => check.id === `queue:${queue}:scheduler-heartbeat`);
+assert.equal(missingCheck?.ok, false);
+assert.equal(missingCheck?.detail?.code, 'scheduler_missing');
+
+await queueSchedulerTick(root, {
+  queue,
+  scheduler: { initialInterval: '1m', minInterval: '1m', maxInterval: '4h' },
+  planOnly: true,
+  forceDue: true
+});
+const healthy = await doctorReport(root);
+const healthyCheck = healthy.checks.find((check) => check.id === `queue:${queue}:scheduler-heartbeat`);
+assert.equal(healthyCheck?.ok, true);
+assert.equal(healthyCheck?.detail?.code, 'scheduler_healthy');
+
+await rm(root, { recursive: true, force: true });
+console.log('scheduler heartbeat self-test passed');

package/skills/taskforce-loop-engineering/SKILL.md

@@ -292,6 +292,8 @@ Summaries must cite the latest run/task/project evidence, verification performed
 
 Use scheduler ticks only after manual verification. Adaptive schedules may speed up with successful queued work and back off on empty queues, failures, long runs, or human gates.
 
+`queue-scheduler-tick` is adaptive cadence logic, not a resident daemon. A cron, systemd timer, or equivalent external scheduler must wake it regularly. For project queues that promise automatic continuation, set `scheduler.required=true` and a bounded `scheduler.heartbeatMaxAge`; `doctor` must fail with `scheduler_missing` whenever queued work exists without a fresh scheduler heartbeat.
+
 Progress notification must be scoped and idempotent. Report failures, human gates, status changes, and terminal completion promptly; throttle routine progress and idle updates.
 
 ## Final Checklist