taskforce-loop-engineering 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.8.2 - 2026-08-07
+
+- Classify transcript-compaction timeouts and selected transport failures as recoverable runtime interruptions instead of development revisions. Preserve accepted checkpoints, rotate the worker session, and return the same project task to the queue with bounded recovery attempts.
+- Bound long-lived project sessions by rotating the worker session after a configurable number of successful project ticks (`retry.sessionMaxTicks`, default 10).
+
+## 0.8.1 - 2026-08-07
+
+- Make the standard OpenClaw installer and upgrade path install and enable a managed per-queue systemd user scheduler, configure required scheduler heartbeats by default, and use an absolute packaged CLI path so systemd does not depend on an interactive shell `PATH`.
+- Make uninstall disable and remove the managed scheduler units, while retaining queue runtime and refusing to overwrite locally modified managed units.
+
 ## 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.

package/MIGRATING.md

@@ -49,6 +49,7 @@ Use `--confirm-install` only after resolving path conflicts. Existing queue runt
 - Worker agent names are installation settings and are not fixed to Ironman.
 - Every task uses an isolated `agent:<worker>:loop-task-<task-id>` session.
 - Asynchronous delivery requires recorded source `channel` and `target`; missing routing metadata fails closed.
+- A confirmed install or managed upgrade now creates and enables a per-queue systemd user scheduler. Queue configs require its heartbeat, so queued project work cannot silently wait forever. Uninstall disables and removes the managed units while retaining queue runtime.
 - `repair-plan` is read-only. Version 0.6 does not add an automatic configuration repair command.
 
 After installation or upgrade, validate the integration:

package/README.md

@@ -59,6 +59,11 @@ already loop-managed to prevent recursive re-enqueue. Existing generated files
 are not overwritten unless `--force` is supplied after review. The installed
 conversation policy treats `走 loop` as enqueue plus immediate execution;
 `只入队` and `只排队` remain explicit queue-only overrides.
+The confirmed installer also creates and enables a managed per-queue systemd
+user timer. It wakes the adaptive scheduler once per minute; the persisted
+scheduler cadence still decides whether work is due. Generated queue configs
+require a fresh scheduler heartbeat, so queued work fails `doctor` with
+`scheduler_missing` instead of waiting indefinitely when the timer is absent.
 After every installed runner tick, the wrapper idempotently scans human-input
 gates and terminal tasks. The generated notifier delivers through
 `openclaw message send` using the task's recorded `channel`, `target`, `account`,
@@ -102,10 +107,12 @@ loop-engineering-openclaw-manage --root /path/to/workspace --action uninstall-pl
 loop-engineering-openclaw-manage --root /path/to/workspace --action uninstall --confirm-uninstall
 ```
 
-The installer manifest records SHA-256 hashes for generated files and the exact
-managed `AGENTS.md` block. Upgrade/uninstall refuses when managed content was
-edited. Uninstall removes only clean managed files and that exact instructions
-block; queue runtime is explicitly retained.
+The installer manifest records SHA-256 hashes for generated files, systemd
+units, and the exact managed `AGENTS.md` block. Upgrade/uninstall refuses when
+managed content was edited. Upgrade installs and enables the scheduler for
+older managed integrations. Uninstall first disables the timer, then removes
+only clean managed files, units, and that exact instructions block; queue
+runtime is explicitly retained.
 
 ## Commands
 

package/lib/core.mjs

@@ -2912,10 +2912,19 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
   const reviseCount = effectiveReviews.filter((item) => item.status === 'revise').length;
   const blockedCount = effectiveReviews.filter((item) => item.status === 'blocked').length;
   const dispatchStatus = context.dispatchStatus ?? 'unknown';
+  const dispatchFailure = context.dispatchFailureClassification ?? null;
   const projectCompletionAccepted = effectiveReviews.some((review) => review.projectCompletion?.status === 'accepted');
   let outcome = 'needs_revision';
 
-  if (dispatchStatus === 'blocked_preflight') {
+  if (dispatchStatus === 'runtime_interrupted') {
+    outcome = 'runtime_interrupted';
+    reasons.push(`A recoverable runtime interruption stopped the worker${dispatchFailure?.category ? ` (${dispatchFailure.category})` : ''}.`);
+    nextActions.push('Rotate the worker session and resume from the latest durable checkpoint without creating a development revision.');
+  } else if (dispatchStatus === 'runtime_blocked') {
+    outcome = 'runtime_blocked';
+    reasons.push('Recoverable runtime interruption retries were exhausted.');
+    nextActions.push('Inspect the runtime transport/session failure before resuming the project.');
+  } else if (dispatchStatus === 'blocked_preflight') {
     outcome = 'blocked';
     reasons.push('Preflight blocked the task before development dispatch.');
     nextActions.push('Resolve preflight findings and rerun the queue task.');
@@ -3031,6 +3040,8 @@ function queueStatusFromFinalJudgement(currentStatus, finalJudgement) {
   const outcome = finalJudgement.judgement.outcome;
   if (outcome === 'ready_to_apply') return currentStatus;
   if (outcome === 'project_in_progress') return outcome;
+  if (outcome === 'runtime_interrupted') return outcome;
+  if (outcome === 'runtime_blocked') return outcome;
   if (outcome === 'ready_for_human_review') return outcome;
   return outcome;
 }
@@ -7827,7 +7838,16 @@ const DEFAULT_REQUIRES_HUMAN_ACTION_PATTERNS = [
   '用户限制'
 ];
 
-function dispatchFailureClassification(result, retry = {}) {
+const DEFAULT_RECOVERABLE_RUNTIME_PATTERNS = [
+  { category: 'compaction_timeout', pattern: 'compaction timed out' },
+  { category: 'compaction_timeout', pattern: 'transcript compaction failed' },
+  { category: 'transport_error', pattern: 'connection reset' },
+  { category: 'transport_error', pattern: 'socket hang up' },
+  { category: 'transport_error', pattern: 'network error' },
+  { category: 'rate_limit', pattern: 'rate limit' }
+];
+
+export function dispatchFailureClassification(result, retry = {}) {
   if (!result || result.exitCode === 0) {
     return {
       category: 'ok',
@@ -7839,6 +7859,7 @@ function dispatchFailureClassification(result, retry = {}) {
     return {
       category: 'timeout',
       requiresHumanAction: false,
+      recoverableRuntime: true,
       matchedPattern: null
     };
   }
@@ -7849,12 +7870,24 @@ function dispatchFailureClassification(result, retry = {}) {
     return {
       category: 'requires_human_action',
       requiresHumanAction: true,
+      recoverableRuntime: false,
       matchedPattern: matched
     };
   }
+  const runtimePatterns = retry.recoverableRuntimePatterns ?? DEFAULT_RECOVERABLE_RUNTIME_PATTERNS;
+  const runtimeMatch = runtimePatterns.find((entry) => output.includes(String(entry.pattern ?? entry).toLowerCase()));
+  if (runtimeMatch) {
+    return {
+      category: runtimeMatch.category ?? 'runtime_interruption',
+      requiresHumanAction: false,
+      recoverableRuntime: true,
+      matchedPattern: runtimeMatch.pattern ?? runtimeMatch
+    };
+  }
   return {
     category: 'retryable_failure',
     requiresHumanAction: false,
+    recoverableRuntime: false,
     matchedPattern: null
   };
 }
@@ -8264,6 +8297,7 @@ export async function runQueueOnce(root, options) {
         const runContext = {
           env: {
             ...taskPlanningEnv(root, taskContract, acceptancePlan, devPlan),
+            LOOP_SESSION_GENERATION: String(task.runtimeSessionGeneration ?? 0),
             LOOP_HUMAN_INPUT_CONTEXT_FILE: humanInputContextFile,
             LOOP_HUMAN_INPUT_CONTEXT_FILE_REL: path.relative(root, humanInputContextFile)
           },
@@ -8312,9 +8346,17 @@ export async function runQueueOnce(root, options) {
             const verifyOk = verification.every((entry) => entry.result.exitCode === 0);
             finalStatus = verifyOk ? 'completed' : 'verify_failed';
           } else {
-            finalStatus = dispatch?.exitCode === 0
-              ? 'completed'
-              : dispatchClassification?.requiresHumanAction ? 'needs_human_input' : 'failed';
+            if (dispatch?.exitCode === 0) {
+              finalStatus = 'completed';
+            } else if (dispatchClassification?.requiresHumanAction) {
+              finalStatus = 'needs_human_input';
+            } else if (dispatchClassification?.recoverableRuntime) {
+              const recoveryCount = Number(task.runtimeRecoveryCount ?? 0);
+              const recoveryMax = Number(options.retry?.runtimeRecoveryMaxAttempts ?? 2);
+              finalStatus = recoveryCount < recoveryMax ? 'runtime_interrupted' : 'runtime_blocked';
+            } else {
+              finalStatus = 'failed';
+            }
           }
         }
         worktreeInspection = await inspectWorktree(worktree);
@@ -8361,6 +8403,7 @@ export async function runQueueOnce(root, options) {
       });
       if (!finalJudgement) finalJudgement = await writeFinalJudgement(root, queue, task, taskContract, acceptancePlan, devPlan, checkpoints, acceptanceReviews, {
         dispatchStatus: finalStatus,
+        dispatchFailureClassification: dispatchAttempts[dispatchAttempts.length - 1]?.failureClassification ?? null,
         verificationFailed: verification.some((entry) => entry.result.exitCode !== 0)
       });
       progress.emit('final-judge', finalJudgement.judgement.outcome, `Final judgement: ${finalJudgement.judgement.outcome}`, {
@@ -8397,6 +8440,7 @@ export async function runQueueOnce(root, options) {
     if (!finalJudgement) {
       finalJudgement = await writeFinalJudgement(root, queue, task, taskContract, acceptancePlan, devPlan, checkpoints, acceptanceReviews, {
         dispatchStatus: finalStatus,
+        dispatchFailureClassification: dispatchAttempts[dispatchAttempts.length - 1]?.failureClassification ?? null,
         verificationFailed: verification.some((entry) => entry.result.exitCode !== 0)
       });
       finalStatus = queueStatusFromFinalJudgement(finalStatus, finalJudgement);
@@ -8405,13 +8449,13 @@ export async function runQueueOnce(root, options) {
       revisionRequest = await writeRevisionRequest(root, queue, task, taskContract, acceptancePlan, devPlan, finalJudgement, acceptanceReviews);
     }
 
-    destination = finalStatus === 'project_in_progress'
+    destination = ['project_in_progress', 'runtime_interrupted'].includes(finalStatus)
       ? queueSubdirFor(root, queue, 'inbox')
       : finalStatus === 'completed'
       ? queueSubdirFor(root, queue, 'done')
       : finalStatus === 'superseded' ? queueSubdirFor(root, queue, 'canceled')
       : queueSubdirFor(root, queue, 'failed');
-    exitCode = ['completed', 'superseded', 'project_in_progress'].includes(finalStatus) ? 0 : 1;
+    exitCode = ['completed', 'superseded', 'project_in_progress', 'runtime_interrupted'].includes(finalStatus) ? 0 : 1;
 
     const finishedAt = new Date().toISOString();
     progress.emit('queue', finalStatus === 'completed' ? 'completed' : finalStatus === 'project_in_progress' ? 'continued' : 'needs_attention', `Task finished with status ${finalStatus}`, {
@@ -8421,7 +8465,7 @@ export async function runQueueOnce(root, options) {
     });
     const completedTask = {
       ...task,
-      status: finalStatus === 'project_in_progress' ? 'queued' : finalStatus,
+      status: ['project_in_progress', 'runtime_interrupted'].includes(finalStatus) ? 'queued' : finalStatus,
       startedAt,
       finishedAt,
       attempts: (task.attempts ?? 0) + Math.max(dispatchAttempts.length, dispatch ? 1 : 0),
@@ -8430,6 +8474,19 @@ export async function runQueueOnce(root, options) {
     if (finalStatus === 'project_in_progress') {
       completedTask.projectContinuedAt = finishedAt;
       completedTask.projectContinuationCount = (task.projectContinuationCount ?? 0) + 1;
+      completedTask.runtimeRecoveryCount = 0;
+      const sessionMaxTicks = Math.max(1, Number(options.retry?.sessionMaxTicks ?? 10));
+      if (completedTask.projectContinuationCount % sessionMaxTicks === 0) {
+        completedTask.runtimeSessionGeneration = Number(task.runtimeSessionGeneration ?? 0) + 1;
+        completedTask.sessionRotatedAt = finishedAt;
+        completedTask.sessionRotationReason = 'bounded_tick_limit';
+      }
+    }
+    if (finalStatus === 'runtime_interrupted') {
+      completedTask.runtimeRecoveryCount = Number(task.runtimeRecoveryCount ?? 0) + 1;
+      completedTask.runtimeSessionGeneration = Number(task.runtimeSessionGeneration ?? 0) + 1;
+      completedTask.runtimeInterruptedAt = finishedAt;
+      completedTask.runtimeInterruption = dispatchAttempts[dispatchAttempts.length - 1]?.failureClassification ?? null;
     }
     const completedFile = path.join(destination, path.basename(activeFile));
     await writeJson(completedFile, completedTask);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",

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

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { buildFinalJudgement, selectEffectiveAcceptanceReviews } from '../lib/core.mjs';
+import { buildFinalJudgement, dispatchFailureClassification, 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' };
@@ -16,6 +16,35 @@ const baseContract = { task_id: 't1', risk_level: 'L1', requires_human_gate: fal
   assert.equal(selectEffectiveAcceptanceReviews(devPlan, reviews)[0].checkpointId, 'cp10');
 }
 
+{
+  const classification = dispatchFailureClassification({
+    exitCode: 1,
+    timedOut: false,
+    stderr: 'CLI transcript compaction failed: Compaction timed out',
+    stdout: ''
+  });
+  assert.equal(classification.category, 'compaction_timeout');
+  assert.equal(classification.recoverableRuntime, true);
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{ checkpointId: 'cp38', sequence: 38, status: 'accepted', projectCompletion: { status: 'in_progress' } }] };
+  const judgement = buildFinalJudgement(
+    { ...baseContract, task_scope: 'project' },
+    basePlan,
+    devPlan,
+    { count: 38 },
+    reviews,
+    {
+      dispatchStatus: 'runtime_interrupted',
+      dispatchFailureClassification: { category: 'compaction_timeout', recoverableRuntime: true }
+    }
+  );
+  assert.equal(judgement.outcome, 'runtime_interrupted');
+  assert.equal(judgement.reasons.some((reason) => reason.includes('development')), false);
+}
+
 {
   const devPlan = { checkpoints: [{ id: 'cp1' }] };
   const reviews = {

package/scripts/openclaw-install-self-test.mjs

@@ -7,6 +7,10 @@ import path from 'node:path';
 const root = await mkdtemp(path.join(tmpdir(), 'loop-openclaw-install-'));
 const deliveryCapture = path.join(root, 'delivery.json');
 const mockOpenClaw = path.join(root, 'mock-openclaw.mjs');
+const mockSystemctl = path.join(root, 'mock-systemctl.mjs');
+const systemctlCapture = path.join(root, 'systemctl-calls.jsonl');
+process.env.XDG_CONFIG_HOME = path.join(root, 'xdg');
+process.env.SYSTEMCTL_CAPTURE = systemctlCapture;
 await writeFile(mockOpenClaw, `#!/usr/bin/env node
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -24,6 +28,11 @@ else {
 }
 `);
 await chmod(mockOpenClaw, 0o755);
+await writeFile(mockSystemctl, `#!/usr/bin/env node
+import { appendFile } from 'node:fs/promises';
+if (process.env.SYSTEMCTL_CAPTURE) await appendFile(process.env.SYSTEMCTL_CAPTURE, JSON.stringify(process.argv.slice(2)) + '\\n');
+`);
+await chmod(mockSystemctl, 0o755);
 const installer = new URL('./openclaw-install.mjs', import.meta.url).pathname;
 function run(args) {
   return new Promise((resolve) => {
@@ -34,21 +43,39 @@ function run(args) {
     child.on('close', (code) => resolve({ code, stdout, stderr }));
   });
 }
-const plan = await run(['--root', root, '--queue', 'test-tasks', '--openclaw-bin', mockOpenClaw, '--json']);
+const installBase = ['--root', root, '--queue', 'test-tasks', '--openclaw-bin', mockOpenClaw, '--systemctl-bin', mockSystemctl];
+const plan = await run([...installBase, '--json']);
 const planReport = JSON.parse(plan.stdout);
 if (plan.code !== 0 || planReport.status !== 'plan_only' || planReport.workerAgent !== 'builder' || planReport.workerSelection !== 'only_available' || !planReport.workerValidated || planReport.createsWorkerAgent) throw new Error(`plan failed: ${plan.stderr}`);
-const missingWorker = await run(['--root', root, '--queue', 'test-tasks', '--worker-agent', 'missing', '--openclaw-bin', mockOpenClaw, '--json']);
+const missingWorker = await run([...installBase, '--worker-agent', 'missing', '--json']);
 if (missingWorker.code === 0 || !missingWorker.stderr.includes('does not exist')) throw new Error('installer accepted a missing worker agent');
-const install = await run(['--root', root, '--queue', 'test-tasks', '--worker-agent', 'builder', '--openclaw-bin', mockOpenClaw, '--confirm-install', '--json']);
+const install = await run([...installBase, '--worker-agent', 'builder', '--confirm-install', '--json']);
 if (install.code !== 0 || JSON.parse(install.stdout).status !== 'installed') throw new Error(`install failed: ${install.stderr}`);
 const queue = JSON.parse(await readFile(path.join(root, 'configs/loops/queues/test-tasks.json'), 'utf8'));
 if (queue.dispatcher !== 'node scripts/loops/openclaw-loop-dispatch.mjs') throw new Error('dispatcher was not installed');
+if (queue.scheduler?.required !== true || queue.scheduler?.heartbeatMaxAgeMs !== 300000) throw new Error('required scheduler heartbeat was not installed');
 const dispatcher = await readFile(path.join(root, 'scripts/loops/openclaw-loop-dispatch.mjs'), 'utf8');
-if (!dispatcher.includes('already loop-managed') || !dispatcher.includes("'--agent', \"builder\"") || !dispatcher.includes('LOOP_LATEST_AMENDMENT_FILE')) throw new Error('worker, recursion guard, or amendment polling missing');
+if (!dispatcher.includes('already loop-managed') || !dispatcher.includes("'--agent', \"builder\"") || !dispatcher.includes('LOOP_LATEST_AMENDMENT_FILE') || !dispatcher.includes('LOOP_SESSION_GENERATION') || !dispatcher.includes('-g${sessionGeneration}')) throw new Error('worker, recursion guard, amendment polling, or session generation missing');
+if (queue.retry?.runtimeRecoveryMaxAttempts !== 2 || queue.retry?.sessionMaxTicks !== 10) throw new Error('bounded runtime recovery policy was not installed');
 const instructions = await readFile(path.join(root, 'AGENTS.md'), 'utf8');
 if (!instructions.includes('走 loop') || !instructions.includes('immediately execute')) throw new Error('conversation instructions missing');
 const wrapper = await readFile(path.join(root, 'scripts/loops/openclaw-loop.mjs'), 'utf8');
-if (!wrapper.includes('--supersede-active') || !wrapper.includes('--amend-active') || !wrapper.includes('--progress-notify-command') || !wrapper.includes('runWhenUnlocked') || wrapper.includes("run-queue-drain', '--config'") || !wrapper.includes('queue-human-input-notify') || !wrapper.includes('queue-terminal-notify') || !wrapper.includes('只入队')) throw new Error('supersede/amend routing, live progress, async notification, or queue-only routing missing');
+if (!wrapper.includes('--supersede-active') || !wrapper.includes('--amend-active') || !wrapper.includes('--progress-notify-command') || !wrapper.includes('runWhenUnlocked') || wrapper.includes("run-queue-drain', '--config'") || wrapper.includes("spawn('loop-engineering'") || !wrapper.includes('queue-human-input-notify') || !wrapper.includes('queue-terminal-notify') || !wrapper.includes('queue-scheduler-tick') || !wrapper.includes('只入队')) throw new Error('supersede/amend routing, absolute CLI, scheduler, live progress, async notification, or queue-only routing missing');
+const serviceFile = path.join(process.env.XDG_CONFIG_HOME, 'systemd/user/openclaw-loop-test-tasks-scheduler.service');
+const timerFile = path.join(process.env.XDG_CONFIG_HOME, 'systemd/user/openclaw-loop-test-tasks-scheduler.timer');
+const service = await readFile(serviceFile, 'utf8');
+const timer = await readFile(timerFile, 'utf8');
+if (!service.includes('scheduler-tick') || !timer.includes('OnUnitActiveSec=1min')) throw new Error('scheduler systemd units were not installed');
+const installSystemctlCalls = await readFile(systemctlCapture, 'utf8');
+if (!installSystemctlCalls.includes('["--user","enable","--now","openclaw-loop-test-tasks-scheduler.timer"]')) throw new Error('scheduler timer was not enabled');
+const schedulerTick = await new Promise((resolve) => {
+  const child = spawn(process.execPath, [path.join(root, 'scripts/loops/openclaw-loop.mjs'), 'scheduler-tick', '--force-due', '--plan-only'], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = ''; let stderr = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.on('close', (code) => resolve({ code, stdout, stderr }));
+});
+if (schedulerTick.code !== 0) throw new Error(`installed scheduler tick failed: ${schedulerTick.stderr || schedulerTick.stdout}`);
+const schedulerState = JSON.parse(await readFile(path.join(root, 'runtime/loops/test-tasks/scheduler/state.json'), 'utf8'));
+if (!schedulerState.generatedAt || !schedulerState.nextRunAt) throw new Error('installed scheduler tick did not persist its heartbeat and cadence');
 const notifier = await readFile(path.join(root, 'scripts/loops/openclaw-loop-notify.mjs'), 'utf8');
 if (!notifier.includes("'message', 'send'") || !notifier.includes('source.channel') || !notifier.includes('source.target')) throw new Error('channel-neutral notifier missing');
 const delivery = await new Promise((resolve) => {
@@ -100,7 +127,7 @@ for (const generated of ['scripts/loops/openclaw-loop-dispatch.mjs', 'scripts/lo
   });
   if (check.code !== 0) throw new Error(`generated script syntax failed: ${generated}: ${check.stderr}`);
 }
-const conflict = await run(['--root', root, '--queue', 'test-tasks', '--worker-agent', 'builder', '--openclaw-bin', mockOpenClaw, '--confirm-install', '--json']);
+const conflict = await run([...installBase, '--worker-agent', 'builder', '--confirm-install', '--json']);
 if (conflict.code === 0) throw new Error('installer overwrote existing files without --force');
 const manager = new URL('./openclaw-manage.mjs', import.meta.url).pathname;
 async function manage(args) {
@@ -126,4 +153,7 @@ const uninstall = await manage(['--action', 'uninstall', '--confirm-uninstall'])
 if (uninstall.code !== 0 || JSON.parse(uninstall.stdout).status !== 'uninstalled') throw new Error(`uninstall failed: ${uninstall.stderr}`);
 if (!await readFile(path.join(root, 'runtime/loops/test-tasks/state.json'), 'utf8').catch(() => 'retained')) throw new Error('unexpected runtime cleanup result');
 if (await readFile(path.join(root, 'scripts/loops/openclaw-loop.mjs'), 'utf8').then(() => true).catch(() => false)) throw new Error('managed wrapper survived uninstall');
+if (await readFile(serviceFile, 'utf8').then(() => true).catch(() => false) || await readFile(timerFile, 'utf8').then(() => true).catch(() => false)) throw new Error('managed scheduler units survived uninstall');
+const finalSystemctlCalls = await readFile(systemctlCapture, 'utf8');
+if (!finalSystemctlCalls.includes('["--user","disable","--now","openclaw-loop-test-tasks-scheduler.timer"]')) throw new Error('scheduler timer was not disabled during uninstall');
 console.log('openclaw installer self-test passed');

package/scripts/openclaw-install.mjs

@@ -5,13 +5,14 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 
 function parseArgs(argv) {
-  const out = { root: process.cwd(), queue: 'agent-tasks', workerAgent: null, openclawBin: 'openclaw', json: false, confirmInstall: false, force: false };
+  const out = { root: process.cwd(), queue: 'agent-tasks', workerAgent: null, openclawBin: 'openclaw', systemctlBin: 'systemctl', json: false, confirmInstall: false, force: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--root') out.root = path.resolve(argv[++i]);
     else if (arg === '--queue') out.queue = argv[++i];
     else if (arg === '--worker-agent') out.workerAgent = argv[++i];
     else if (arg === '--openclaw-bin') out.openclawBin = argv[++i];
+    else if (arg === '--systemctl-bin') out.systemctlBin = argv[++i];
     else if (arg === '--confirm-install') out.confirmInstall = true;
     else if (arg === '--force') out.force = true;
     else if (arg === '--json') out.json = true;
@@ -21,6 +22,10 @@ function parseArgs(argv) {
   return out;
 }
 
+function systemdEscape(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
 function safeId(value, label) {
   if (!/^[a-zA-Z0-9._-]+$/.test(value)) throw new Error(`${label} contains unsupported characters.`);
   return value;
@@ -63,6 +68,7 @@ function dispatcherSource({ workerAgent, openclawBin }) {
 import { readFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 const task = JSON.parse(await readFile(process.env.LOOP_TASK_FILE, 'utf8'));
+const sessionGeneration = Number.parseInt(process.env.LOOP_SESSION_GENERATION || '0', 10) || 0;
 const prompt = [
   'You are receiving an already loop-managed task.',
   'Do not route or enqueue this task again, even if its quoted request contains a loop trigger.',
@@ -79,20 +85,20 @@ const prompt = [
 ].join('\\n');
 const child = spawn(${JSON.stringify(openclawBin)}, [
   'agent', '--agent', ${JSON.stringify(workerAgent)},
-  '--session-key', \`agent:${workerAgent}:loop-task-\${task.id}\`,
+  '--session-key', \`agent:${workerAgent}:loop-task-\${task.id}-g\${sessionGeneration}\`,
   '--message', prompt, '--json', '--timeout', '1800'
 ], { cwd: process.cwd(), env: process.env, stdio: 'inherit' });
 child.on('close', (code, signal) => { process.exitCode = code ?? (signal ? 128 : 1); });
 `;
 }
 
-function wrapperSource({ queue }) {
+function wrapperSource({ queue, loopBin }) {
   return `#!/usr/bin/env node
 import { spawn } from 'node:child_process';
 const [command, ...rest] = process.argv.slice(2);
 function run(args) {
   return new Promise((resolve) => {
-    const child = spawn('loop-engineering', args, { cwd: process.cwd(), env: process.env, stdio: 'inherit' });
+    const child = spawn(process.execPath, [${JSON.stringify(loopBin)}, ...args], { cwd: process.cwd(), env: process.env, stdio: 'inherit' });
     child.on('close', (code, signal) => resolve(code ?? (signal ? 128 : 1)));
   });
 }
@@ -121,6 +127,11 @@ if (command === 'route') {
   const humanNotifyCode = await run(['queue-human-input-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/openclaw-loop-notify.mjs']);
   const terminalNotifyCode = await run(['queue-terminal-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/openclaw-loop-notify.mjs']);
   process.exitCode = runCode || humanNotifyCode || terminalNotifyCode;
+} else if (command === 'scheduler-tick') {
+  const tickCode = await run(['queue-scheduler-tick', '--config', ${JSON.stringify(`configs/loops/queues/${queue}.json`)}, '--progress-notify-command', 'node scripts/loops/openclaw-loop-notify.mjs', ...rest]);
+  const humanNotifyCode = await run(['queue-human-input-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/openclaw-loop-notify.mjs']);
+  const terminalNotifyCode = await run(['queue-terminal-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/openclaw-loop-notify.mjs']);
+  process.exitCode = tickCode || humanNotifyCode || terminalNotifyCode;
 } else {
   console.error('Usage: node scripts/loops/openclaw-loop.mjs route --message "走 loop：任务" [source metadata]');
   process.exitCode = 1;
@@ -128,6 +139,14 @@ if (command === 'route') {
 `;
 }
 
+function schedulerServiceSource({ root, queue }) {
+  return `[Unit]\nDescription=Taskforce Loop Engineering scheduler for ${queue}\nAfter=default.target\n\n[Service]\nType=oneshot\nWorkingDirectory="${systemdEscape(root)}"\nExecStart="${systemdEscape(process.execPath)}" "${systemdEscape(path.join(root, 'scripts', 'loops', 'openclaw-loop.mjs'))}" scheduler-tick --json\n`;
+}
+
+function schedulerTimerSource({ queue }) {
+  return `[Unit]\nDescription=Wake Taskforce Loop Engineering scheduler for ${queue}\n\n[Timer]\nOnBootSec=30s\nOnUnitActiveSec=1min\nAccuracySec=10s\nPersistent=true\nUnit=openclaw-loop-${queue}-scheduler.service\n\n[Install]\nWantedBy=timers.target\n`;
+}
+
 function notifierSource({ openclawBin }) {
   return `#!/usr/bin/env node
 import { spawn } from 'node:child_process';
@@ -164,13 +183,17 @@ function instructionsBlock({ queue }) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
-    console.log('Usage: loop-engineering-openclaw-install [--root workspace] [--queue agent-tasks] [--worker-agent agent-id] [--openclaw-bin openclaw] [--confirm-install] [--force] [--json]');
+    console.log('Usage: loop-engineering-openclaw-install [--root workspace] [--queue agent-tasks] [--worker-agent agent-id] [--openclaw-bin openclaw] [--systemctl-bin systemctl] [--confirm-install] [--force] [--json]');
     return;
   }
   safeId(args.queue, 'queue');
   if (args.workerAgent) safeId(args.workerAgent, 'worker agent');
   const worker = await resolveWorkerAgent(args);
   args.workerAgent = worker.workerAgent;
+  args.loopBin = new URL('../bin/loop-engineering.mjs', import.meta.url).pathname;
+  const systemdUserDir = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'systemd', 'user');
+  const schedulerUnit = `openclaw-loop-${args.queue}-scheduler.service`;
+  const schedulerTimer = `openclaw-loop-${args.queue}-scheduler.timer`;
   const files = {
     workspaceHealth: path.join(args.root, 'configs', 'loops', 'workspace-health.json'),
     queueConfig: path.join(args.root, 'configs', 'loops', 'queues', `${args.queue}.json`),
@@ -178,11 +201,13 @@ async function main() {
     wrapper: path.join(args.root, 'scripts', 'loops', 'openclaw-loop.mjs'),
     notifier: path.join(args.root, 'scripts', 'loops', 'openclaw-loop-notify.mjs'),
     manifest: path.join(args.root, 'runtime', 'loop-engineering-openclaw-install.json'),
-    instructions: path.join(args.root, 'AGENTS.md')
+    instructions: path.join(args.root, 'AGENTS.md'),
+    schedulerService: path.join(systemdUserDir, schedulerUnit),
+    schedulerTimer: path.join(systemdUserDir, schedulerTimer)
   };
   const conflicts = [];
   for (const [kind, file] of Object.entries(files)) if (!['instructions', 'workspaceHealth', 'manifest'].includes(kind) && await exists(file)) conflicts.push(path.relative(args.root, file));
-  const report = { version: 1, status: args.confirmInstall ? 'installed' : 'plan_only', readOnly: !args.confirmInstall, root: args.root, queue: args.queue, workerAgent: args.workerAgent, workerSelection: worker.selection, availableAgents: worker.availableAgents, workerValidated: true, createsWorkerAgent: false, openclawBin: args.openclawBin, files: Object.fromEntries(Object.entries(files).map(([key, file]) => [key, path.relative(args.root, file)])), conflicts };
+  const report = { version: 1, status: args.confirmInstall ? 'installed' : 'plan_only', readOnly: !args.confirmInstall, root: args.root, queue: args.queue, workerAgent: args.workerAgent, workerSelection: worker.selection, availableAgents: worker.availableAgents, workerValidated: true, createsWorkerAgent: false, openclawBin: args.openclawBin, systemctlBin: args.systemctlBin, scheduler: { required: true, unit: schedulerUnit, timer: schedulerTimer }, files: Object.fromEntries(Object.entries(files).map(([key, file]) => [key, path.relative(args.root, file)])), conflicts };
   report.next = args.confirmInstall ? 'Run loop-engineering-openclaw-doctor, then route a harmless smoke task.' : 'Review this plan, then rerun with --confirm-install.';
   if (conflicts.length && !args.force && args.confirmInstall) throw new Error(`Refusing to overwrite: ${conflicts.join(', ')}. Use --force after review.`);
   if (args.confirmInstall) {
@@ -203,28 +228,42 @@ async function main() {
       dispatcher: 'node scripts/loops/openclaw-loop-dispatch.mjs',
       preflightConfig: 'configs/loops/workspace-health.json',
       timeoutMs: 1800000, leaseMs: 1860000, staleActiveMs: 3600000,
-      retry: { maxAttempts: 1, retryDelayMs: 0, retryExitCodes: [1], requiresHumanActionPatterns: ['requires human', '需要人工', 'Permission denied', 'Operation not permitted'] },
+      scheduler: { required: true, heartbeatMaxAgeMs: 300000, initialInterval: '1m', minInterval: '1m', maxInterval: '4h', speedupFactor: 0.5, backoffFactor: 2, idleBackoffFactor: 2, humanGateBackoffFactor: 3, longRunHeadroomFactor: 1.25, jitter: '10s' },
+      retry: { maxAttempts: 1, runtimeRecoveryMaxAttempts: 2, sessionMaxTicks: 10, retryDelayMs: 0, retryExitCodes: [1], requiresHumanActionPatterns: ['requires human', '需要人工', 'Permission denied', 'Operation not permitted'] },
       revisionPolicy: { enabled: true, maxRevisionRounds: 3, sameFailureThreshold: 2, requireStrategyChange: true }
     }, null, 2)}\n`;
     const dispatcherContent = dispatcherSource(args);
     const wrapperContent = wrapperSource(args);
     const notifierContent = notifierSource(args);
+    const schedulerServiceContent = schedulerServiceSource(args);
+    const schedulerTimerContent = schedulerTimerSource(args);
     await writeFile(files.queueConfig, queueContent);
     await writeFile(files.dispatcher, dispatcherContent);
     await writeFile(files.wrapper, wrapperContent);
     await writeFile(files.notifier, notifierContent);
+    await mkdir(systemdUserDir, { recursive: true });
+    await writeFile(files.schedulerService, schedulerServiceContent);
+    await writeFile(files.schedulerTimer, schedulerTimerContent);
+    const daemonReload = await run(args.systemctlBin, ['--user', 'daemon-reload'], { cwd: args.root });
+    if (daemonReload.code !== 0) throw new Error(`Cannot reload user systemd units: ${(daemonReload.stderr || daemonReload.stdout).trim() || `exit ${daemonReload.code}`}`);
+    const enableTimer = await run(args.systemctlBin, ['--user', 'enable', '--now', schedulerTimer], { cwd: args.root });
+    if (enableTimer.code !== 0) throw new Error(`Cannot enable Loop scheduler timer ${schedulerTimer}: ${(enableTimer.stderr || enableTimer.stdout).trim() || `exit ${enableTimer.code}`}`);
     const instructions = await exists(files.instructions) ? await readFile(files.instructions, 'utf8') : '';
     const managedInstructions = instructionsBlock(args);
     if (!instructions.includes('<!-- loop-engineering:openclaw:start -->')) await appendFile(files.instructions, managedInstructions);
     await mkdir(path.dirname(files.manifest), { recursive: true });
     await writeFile(files.manifest, `${JSON.stringify({
-      version: 1, queue: args.queue, workerAgent: args.workerAgent, openclawBin: args.openclawBin, installedAt: new Date().toISOString(),
+      version: 2, queue: args.queue, workerAgent: args.workerAgent, openclawBin: args.openclawBin, systemctlBin: args.systemctlBin, installedAt: new Date().toISOString(),
       managedFiles: [
         { path: path.relative(args.root, files.queueConfig), sha256: sha256(queueContent) },
         { path: path.relative(args.root, files.dispatcher), sha256: sha256(dispatcherContent) },
         { path: path.relative(args.root, files.wrapper), sha256: sha256(wrapperContent) },
         { path: path.relative(args.root, files.notifier), sha256: sha256(notifierContent) }
       ],
+      managedUnits: [
+        { path: files.schedulerService, unit: schedulerUnit, sha256: sha256(schedulerServiceContent) },
+        { path: files.schedulerTimer, unit: schedulerTimer, sha256: sha256(schedulerTimerContent) }
+      ],
       managedInstructions: { path: 'AGENTS.md', sha256: sha256(managedInstructions), content: managedInstructions },
       retainedOnUninstall: [`runtime/loops/${args.queue}`]
     }, null, 2)}\n`);

package/scripts/openclaw-manage.mjs

@@ -6,6 +6,13 @@ import path from 'node:path';
 
 const sha256 = (value) => createHash('sha256').update(value).digest('hex');
 async function exists(file) { try { await access(file); return true; } catch { return false; } }
+function run(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; let stderr = ''; child.stdout.on('data', (c) => { stdout += c; }); child.stderr.on('data', (c) => { stderr += c; });
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
 function parseArgs(argv) {
   const out = { root: process.cwd(), action: 'uninstall-plan', json: false, confirm: false };
   for (let i = 0; i < argv.length; i++) {
@@ -36,15 +43,29 @@ async function main() {
     const current = present ? await readFile(file, 'utf8') : '';
     files.push({ path: entry.path, present, clean: present && sha256(current) === entry.sha256 });
   }
+  const units = [];
+  for (const entry of manifest.managedUnits || []) {
+    const present = await exists(entry.path);
+    const current = present ? await readFile(entry.path, 'utf8') : '';
+    units.push({ ...entry, present, clean: present && sha256(current) === entry.sha256 });
+  }
   const agentsFile = path.join(args.root, manifest.managedInstructions?.path || 'AGENTS.md');
   const agentsText = await exists(agentsFile) ? await readFile(agentsFile, 'utf8') : '';
   const block = manifest.managedInstructions?.content || '';
   const instructionsClean = Boolean(block) && sha256(block) === manifest.managedInstructions?.sha256 && agentsText.includes(block);
-  const modified = files.filter((item) => item.present && !item.clean).map((item) => item.path);
-  const plan = { version: 1, action: args.action, readOnly: args.action.endsWith('-plan'), queue: manifest.queue, workerAgent: manifest.workerAgent, files, instructionsClean, modified, retained: manifest.retainedOnUninstall || [], ready: modified.length === 0 && instructionsClean };
+  const modified = [...files.filter((item) => item.present && !item.clean).map((item) => item.path), ...units.filter((item) => item.present && !item.clean).map((item) => item.path)];
+  const plan = { version: 2, action: args.action, readOnly: args.action.endsWith('-plan'), queue: manifest.queue, workerAgent: manifest.workerAgent, files, units, instructionsClean, modified, retained: manifest.retainedOnUninstall || [], ready: modified.length === 0 && instructionsClean };
   if (args.action === 'uninstall') {
     if (!plan.ready) throw new Error(`Refusing uninstall because managed content changed: ${[...modified, ...(!instructionsClean ? ['AGENTS.md managed block'] : [])].join(', ')}`);
+    const timer = units.find((item) => item.unit?.endsWith('.timer'));
+    if (timer) {
+      const stopped = await run(manifest.systemctlBin || 'systemctl', ['--user', 'disable', '--now', timer.unit], args.root);
+      if (stopped.code !== 0) throw new Error(`Cannot disable Loop scheduler timer ${timer.unit}: ${stopped.stderr || stopped.stdout}`);
+    }
     for (const item of files) if (item.present && item.clean) await rm(path.join(args.root, item.path), { force: true });
+    for (const item of units) if (item.present && item.clean) await rm(item.path, { force: true });
+    const reload = await run(manifest.systemctlBin || 'systemctl', ['--user', 'daemon-reload'], args.root);
+    if (reload.code !== 0) throw new Error(`Cannot reload user systemd units: ${reload.stderr || reload.stdout}`);
     await writeFile(agentsFile, agentsText.replace(block, ''));
     await rm(manifestFile, { force: true });
     plan.status = 'uninstalled'; plan.readOnly = false;
@@ -52,7 +73,7 @@ async function main() {
     if (!plan.ready) throw new Error(`Refusing upgrade because managed content changed: ${[...modified, ...(!instructionsClean ? ['AGENTS.md managed block'] : [])].join(', ')}`);
     const installer = new URL('./openclaw-install.mjs', import.meta.url).pathname;
     const result = await new Promise((resolve) => {
-      const child = spawn(process.execPath, [installer, '--root', args.root, '--queue', manifest.queue, '--worker-agent', manifest.workerAgent, '--openclaw-bin', manifest.openclawBin || 'openclaw', '--confirm-install', '--force', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+      const child = spawn(process.execPath, [installer, '--root', args.root, '--queue', manifest.queue, '--worker-agent', manifest.workerAgent, '--openclaw-bin', manifest.openclawBin || 'openclaw', '--systemctl-bin', manifest.systemctlBin || 'systemctl', '--confirm-install', '--force', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
       let stdout = ''; let stderr = ''; child.stdout.on('data', (c) => { stdout += c; }); child.stderr.on('data', (c) => { stderr += c; });
       child.on('close', (code) => resolve({ code, stdout, stderr }));
     });