taskforce-loop-engineering 0.8.4 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.0 - 2026-08-08
+
+- Add a native Hermes Agent conversation integration with a plan-first installer, `hermes -z` one-shot worker dispatcher, `hermes send` notifier, managed scheduler, and source-bound delivery routing.
+- Add a read-only Hermes doctor and disposable end-to-end smoke covering task contracts, checkpoints, final judgement, human-gate scanning, and terminal notification return.
+- Add Hermes integration self-tests, including real systemd unit verification for paths containing spaces and non-ASCII characters.
+- Add an explicit cross-platform installation confirmation summary to both OpenClaw and Hermes plans, showing the target platform, absolute CLI path, workspace, queue, scheduler, notification routing, and write status before installation.
+
+## 0.8.5 - 2026-08-08
+
+- Fixed generated systemd scheduler units so `WorkingDirectory` and `ExecStart` use unquoted, byte-safe systemd path escapes.
+- Added real `systemd-analyze verify` coverage for scheduler paths containing spaces and non-ASCII characters.
+
 ## 0.8.4 - 2026-08-07
 
 - Reclaim queue locks immediately when their recorded owner PID no longer

package/README.md

@@ -1,6 +1,6 @@
 # Taskforce Loop Engineering
 
-OpenClaw-native loop engineering for repeated agent work. It provides a small
+Durable loop engineering for repeated agent work on OpenClaw and Hermes Agent. It provides a small
 Node CLI that executes JSON loop specs, records append-only run artifacts, and
 uses a circuit breaker to escalate repeated failures.
 
@@ -39,8 +39,9 @@ when exactly one exists. If there is no unambiguous choice, it fails with the
 available agent ids and asks for `--worker-agent`; it never creates an agent.
 An explicitly selected worker must already exist.
 
-The default is read-only and reports the selected worker and files it would
-create. After review,
+The default is read-only and prints an installation confirmation summary with
+the target platform, absolute platform CLI path, workspace, queue, scheduler,
+notification routing, and whether writes are enabled. After review,
 install the queue, configurable worker dispatcher, atomic route-and-run wrapper,
 channel-neutral asynchronous notifier, workspace health preflight, and managed
 `AGENTS.md` routing block with:
@@ -114,6 +115,61 @@ 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.
 
+## Hermes Agent conversation installer
+
+Hermes Agent is supported through a native dispatcher and notifier while the
+platform-neutral Loop Engineering CLI continues to own durable task state,
+checkpoints, revisions, and final judgement. Generate a read-only plan first:
+
+```bash
+loop-engineering-hermes-install \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+```
+
+After review, install the Hermes one-shot worker dispatcher, `hermes send`
+notifier, queue wrapper, workspace routing instructions, and managed systemd
+user timer:
+
+```bash
+loop-engineering-hermes-install \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks \
+  --confirm-install
+```
+
+Like the OpenClaw installer, the read-only Hermes plan prints the target
+platform, absolute Hermes CLI path, workspace, queue, scheduler, notification
+routing, and write status before `--confirm-install` can enable changes.
+
+The dispatcher invokes `hermes -z` (`--oneshot`) with the managed task contract and artifact
+paths. Notifications invoke `hermes send --to` without an LLM call. Conversation
+routing must preserve `--source-target` in Hermes
+`platform:chat_id[:thread_id]` form so progress, human gates, and terminal
+results return to the correct chat. The installer records the absolute Hermes
+executable path so systemd does not depend on an interactive shell `PATH`. The
+scheduler uses systemd rather than a
+Hermes Cron agent session, so queue continuity remains entirely artifact-based.
+This managed installer currently targets Linux hosts with systemd user services;
+the platform-neutral core CLI can still run manually on other Hermes platforms.
+
+Validate the integration and then run a disposable read-only end-to-end smoke:
+
+```bash
+loop-engineering-hermes-doctor \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+
+loop-engineering-hermes-smoke \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+```
+
+The doctor checks the Hermes CLI, `hermes send`, generated files, queue wiring,
+and a delivery dry-run. The smoke creates a temporary queue, executes a bounded
+Hermes worker task, verifies contract/plan/final-judgement artifacts, tests the
+notification return path without sending externally, and removes its artifacts.
+
 ## Commands
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -11,12 +11,16 @@
     "loop-engineering-openclaw-doctor": "scripts/openclaw-doctor.mjs",
     "loop-engineering-openclaw-smoke": "scripts/openclaw-smoke.mjs",
     "loop-engineering-openclaw-manage": "scripts/openclaw-manage.mjs",
+    "loop-engineering-hermes-install": "scripts/hermes-install.mjs",
+    "loop-engineering-hermes-doctor": "scripts/hermes-doctor.mjs",
+    "loop-engineering-hermes-smoke": "scripts/hermes-smoke.mjs",
     "run-loop-cron.sh": "scripts/run-loop-cron.sh"
   },
   "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/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",
+    "check:hermes-install": "node --check scripts/hermes-install.mjs && node --check scripts/hermes-doctor.mjs && node --check scripts/hermes-smoke.mjs && node scripts/hermes-install-self-test.mjs",
+    "check": "npm run check:config-drift && npm run check:openclaw-install && npm run check:hermes-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/hermes-doctor.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { access, readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const out = { root: process.cwd(), queue: 'agent-tasks', hermesBin: 'hermes', json: 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 === '--hermes-bin') out.hermesBin = argv[++i]; else if (arg === '--json') out.json = true; else if (arg === '--help' || arg === '-h') out.help = true; else throw new Error(`Unknown argument: ${arg}`); }
+  return out;
+}
+function run(command, args, options = {}) { return new Promise((resolve) => { const child = spawn(command, args, { cwd: options.cwd, env: options.env || process.env, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.stderr.on('data', (chunk) => { stderr += chunk; }); child.on('error', (error) => resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` })); child.on('close', (code, signal) => resolve({ code: code ?? (signal ? 128 : 1), stdout, stderr })); }); }
+async function present(file) { try { await access(file); return true; } catch { return false; } }
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log('Usage: loop-engineering-hermes-doctor [--root workspace] [--queue agent-tasks] [--hermes-bin hermes] [--json]'); return; }
+  const required = [`configs/loops/queues/${args.queue}.json`, 'configs/loops/workspace-health.json', 'scripts/loops/hermes-loop-dispatch.mjs', 'scripts/loops/hermes-loop.mjs', 'scripts/loops/hermes-loop-notify.mjs', 'runtime/loop-engineering-hermes-install.json', 'AGENTS.md'];
+  const checks = []; for (const relative of required) checks.push({ id: `file:${relative}`, ok: await present(path.join(args.root, relative)) });
+  const cli = await run(args.hermesBin, ['--version'], { cwd: args.root }); checks.push({ id: 'hermes_cli', ok: cli.code === 0, detail: (cli.stdout || cli.stderr).trim().slice(0, 300) });
+  const sendHelp = await run(args.hermesBin, ['send', '--help'], { cwd: args.root }); checks.push({ id: 'hermes_send', ok: sendHelp.code === 0, detail: (sendHelp.stdout || sendHelp.stderr).trim().slice(0, 300) });
+  const queueFile = path.join(args.root, `configs/loops/queues/${args.queue}.json`);
+  if (await present(queueFile)) { try { const queue = JSON.parse(await readFile(queueFile, 'utf8')); checks.push({ id: 'queue_config', ok: queue.queue === args.queue && queue.dispatcher === 'node scripts/loops/hermes-loop-dispatch.mjs' }); } catch (error) { checks.push({ id: 'queue_config', ok: false, detail: error.message }); } }
+  const notifier = path.join(args.root, 'scripts/loops/hermes-loop-notify.mjs');
+  if (await present(notifier)) { const dry = await run(process.execPath, [notifier, 'Loop Engineering notification dry-run'], { cwd: args.root, env: { ...process.env, LOOP_NOTIFICATION_DRY_RUN: '1', LOOP_NOTIFICATION_SOURCE: JSON.stringify({ channel: 'telegram', target: 'telegram:loop-doctor-dry-run' }) } }); checks.push({ id: 'notification_dry_run', ok: dry.code === 0 && dry.stdout.includes('"dryRun":true'), detail: (dry.stdout || dry.stderr).trim().slice(0, 500) }); }
+  const failed = checks.filter((check) => !check.ok); const report = { version: 1, platform: 'hermes', status: failed.length ? 'fail' : 'ok', readOnly: true, externalWrite: false, root: args.root, queue: args.queue, checks, failed: failed.map((check) => check.id) };
+  console.log(args.json ? JSON.stringify(report, null, 2) : `Hermes Loop doctor: ${report.status}\nchecks: ${checks.length - failed.length}/${checks.length}\nfailed: ${report.failed.join(', ') || 'none'}`); if (failed.length) process.exitCode = 1;
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { chmod, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop hermes 安装-'));
+const mockHermes = path.join(root, 'mock-hermes.mjs'); const mockSystemctl = path.join(root, 'mock-systemctl.mjs'); const systemctlCapture = path.join(root, 'systemctl.jsonl'); const sendCapture = path.join(root, 'send.json');
+process.env.XDG_CONFIG_HOME = path.join(root, 'xdg'); process.env.SYSTEMCTL_CAPTURE = systemctlCapture;
+await writeFile(path.join(root, 'AGENTS.md'), '# Test workspace\n');
+await writeFile(mockHermes, `#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const args = process.argv.slice(2);
+if (args[0] === '--version') console.log('Hermes Agent v0.20.0');
+else if (args[0] === 'send' && args.includes('--help')) console.log('hermes send --to TARGET MESSAGE');
+else if (args[0] === 'send') { if (process.env.HERMES_SEND_CAPTURE) await writeFile(process.env.HERMES_SEND_CAPTURE, JSON.stringify(args)); console.log('sent'); }
+else if (args.includes('-z')) {
+  if (process.env.LOOP_CHECKPOINTS_DIR) { const dir = path.resolve(process.cwd(), process.env.LOOP_CHECKPOINTS_DIR); await mkdir(dir, { recursive: true }); await writeFile(path.join(dir, 'cp1.json'), JSON.stringify({ version: 1, task_id: process.env.LOOP_TASK_ID, checkpoint_id: 'cp1', status: 'ready_for_acceptance', summary: 'Hermes read-only smoke completed.', files_changed: [], verification: [{ command: 'mock hermes smoke', outcome: 'passed' }], blockers: [], risks: [], next_action: 'acceptance_review' })); }
+  console.log('SMOKE_OK');
+} else process.exitCode = 2;
+`); await chmod(mockHermes, 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);
+function run(command, args, options = {}) { return new Promise((resolve) => { const child = spawn(command, args, { cwd: options.cwd || root, env: options.env || process.env, 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 })); }); }
+const installer = new URL('./hermes-install.mjs', import.meta.url).pathname; const doctor = new URL('./hermes-doctor.mjs', import.meta.url).pathname; const smoke = new URL('./hermes-smoke.mjs', import.meta.url).pathname; const loopBin = new URL('../bin/loop-engineering.mjs', import.meta.url).pathname;
+const base = ['--root', root, '--queue', 'hermes-tasks', '--hermes-bin', mockHermes, '--systemctl-bin', mockSystemctl];
+const plan = await run(process.execPath, [installer, ...base, '--json']); const planReport = JSON.parse(plan.stdout); if (plan.code !== 0 || planReport.status !== 'plan_only' || planReport.confirmationSummary?.targetPlatform !== 'Hermes' || planReport.confirmationSummary?.writesEnabled !== false || !path.isAbsolute(planReport.confirmationSummary?.platformCli || '') || !planReport.confirmationSummary?.notificationTarget.includes('Hermes')) throw new Error(`Hermes install plan failed: ${plan.stderr}`);
+const humanPlan = await run(process.execPath, [installer, ...base]); if (humanPlan.code !== 0 || !humanPlan.stdout.includes('Installation confirmation') || !humanPlan.stdout.includes('target platform: Hermes') || !humanPlan.stdout.includes('writes enabled: no (plan only)')) throw new Error('human-readable Hermes confirmation summary missing');
+const install = await run(process.execPath, [installer, ...base, '--confirm-install', '--json']); if (install.code !== 0 || JSON.parse(install.stdout).status !== 'installed') throw new Error(`Hermes install failed: ${install.stderr}`);
+const queue = JSON.parse(await readFile(path.join(root, 'configs/loops/queues/hermes-tasks.json'), 'utf8')); if (queue.dispatcher !== 'node scripts/loops/hermes-loop-dispatch.mjs' || queue.scheduler?.required !== true) throw new Error('Hermes queue wiring missing');
+const dispatcher = await readFile(path.join(root, 'scripts/loops/hermes-loop-dispatch.mjs'), 'utf8'); if (!dispatcher.includes("'-z', prompt")) throw new Error('Hermes one-shot dispatcher missing');
+const notifier = path.join(root, 'scripts/loops/hermes-loop-notify.mjs'); const notify = await run(process.execPath, [notifier, 'hello from loop'], { env: { ...process.env, HERMES_SEND_CAPTURE: sendCapture, LOOP_NOTIFICATION_SOURCE: JSON.stringify({ channel: 'telegram', target: 'telegram:12345' }) } }); if (notify.code !== 0) throw new Error(`Hermes notifier failed: ${notify.stderr}`);
+const sent = JSON.parse(await readFile(sendCapture, 'utf8')); if (!sent.includes('telegram:12345') || !sent.includes('hello from loop')) throw new Error('Hermes notifier did not preserve delivery target/message');
+const serviceFile = path.join(process.env.XDG_CONFIG_HOME, 'systemd/user/hermes-loop-hermes-tasks-scheduler.service'); const timerFile = path.join(process.env.XDG_CONFIG_HOME, 'systemd/user/hermes-loop-hermes-tasks-scheduler.timer'); const service = await readFile(serviceFile, 'utf8'); if (service.includes('WorkingDirectory="') || !service.includes('\\x20') || !service.includes('\\xe5\\xae\\x89\\xe8\\xa3\\x85')) throw new Error('Hermes systemd paths were not escaped');
+const verify = await run('systemd-analyze', ['verify', serviceFile, timerFile]); if (verify.code !== 0) throw new Error(`Hermes systemd units invalid: ${verify.stderr || verify.stdout}`);
+const doctorResult = await run(process.execPath, [doctor, '--root', root, '--queue', 'hermes-tasks', '--hermes-bin', mockHermes, '--json']); if (doctorResult.code !== 0 || JSON.parse(doctorResult.stdout).status !== 'ok') throw new Error(`Hermes doctor failed: ${doctorResult.stderr || doctorResult.stdout}`);
+const smokeResult = await run(process.execPath, [smoke, '--root', root, '--queue', 'hermes-tasks', '--hermes-bin', mockHermes, '--loop-bin', loopBin, '--json']); if (smokeResult.code !== 0 || JSON.parse(smokeResult.stdout).status !== 'ok') throw new Error(`Hermes smoke failed: ${smokeResult.stderr || smokeResult.stdout}`);
+const calls = await readFile(systemctlCapture, 'utf8'); if (!calls.includes('["--user","enable","--now","hermes-loop-hermes-tasks-scheduler.timer"]')) throw new Error('Hermes scheduler timer was not enabled');
+console.log('hermes installer self-test passed');

package/scripts/hermes-install.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const out = { root: process.cwd(), queue: 'agent-tasks', hermesBin: 'hermes', 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 === '--hermes-bin') out.hermesBin = 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;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function safeId(value, label) { if (!/^[a-zA-Z0-9._-]+$/.test(value)) throw new Error(`${label} contains unsupported characters.`); return value; }
+function systemdEscapePath(value) {
+  return [...Buffer.from(String(value))].map((byte) => /[A-Za-z0-9/_.:-]/.test(String.fromCharCode(byte)) ? String.fromCharCode(byte) : `\\x${byte.toString(16).padStart(2, '0')}`).join('');
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+async function exists(file) { try { await access(file); return true; } catch { return false; } }
+async function resolveExecutable(command) {
+  if (path.isAbsolute(command) || command.includes(path.sep)) {
+    const resolved = path.resolve(command); if (!await exists(resolved)) throw new Error(`Executable not found: ${resolved}`); return resolved;
+  }
+  for (const dir of String(process.env.PATH || '').split(path.delimiter).filter(Boolean)) { const candidate = path.join(dir, command); if (await exists(candidate)) return candidate; }
+  throw new Error(`Executable not found on PATH: ${command}`);
+}
+function run(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env || process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; }); child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` }));
+    child.on('close', (code, signal) => resolve({ code: code ?? (signal ? 128 : 1), stdout, stderr }));
+  });
+}
+
+function formatConfirmationSummary(summary) {
+  return [
+    'Installation confirmation',
+    `  target platform: ${summary.targetPlatform}`,
+    `  platform CLI: ${summary.platformCli}`,
+    `  workspace: ${summary.workspace}`,
+    `  queue: ${summary.queue}`,
+    `  scheduler: ${summary.scheduler}`,
+    `  notification target: ${summary.notificationTarget}`,
+    `  writes enabled: ${summary.writesEnabled ? 'yes' : 'no (plan only)'}`
+  ].join('\n');
+}
+
+function dispatcherSource({ hermesBin }) {
+  return `#!/usr/bin/env node
+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 prompt = [
+  'You are receiving an already loop-managed task.',
+  'Do not route or enqueue this task again.',
+  'Read the task contract, development plan, acceptance plan, and live amendments before implementation.',
+  \`Task id: \${task.id}\`,
+  \`Task contract: \${process.env.LOOP_TASK_CONTRACT_FILE || 'not provided'}\`,
+  \`Development plan: \${process.env.LOOP_DEV_PLAN_FILE || 'not provided'}\`,
+  \`Acceptance plan: \${process.env.LOOP_ACCEPTANCE_PLAN_FILE || 'not provided'}\`,
+  \`Live amendments: \${process.env.LOOP_LATEST_AMENDMENT_FILE || 'not provided'}\`,
+  \`Checkpoints dir: \${process.env.LOOP_CHECKPOINTS_DIR || 'not provided'}\`,
+  '', task.body, '',
+  'Before each checkpoint and final completion, reread the live amendment file. Write a checkpoint when possible and finish with status, evidence, verification, blockers, and next action.'
+].join('\\n');
+const child = spawn(${JSON.stringify(hermesBin)}, ['-z', prompt], { cwd: process.cwd(), env: process.env, stdio: 'inherit' });
+child.on('close', (code, signal) => { process.exitCode = code ?? (signal ? 128 : 1); });
+`;
+}
+
+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(process.execPath, [${JSON.stringify(loopBin)}, ...args], { cwd: process.cwd(), env: process.env, stdio: 'inherit' }); child.on('close', (code, signal) => resolve(code ?? (signal ? 128 : 1))); }); }
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function runWhenUnlocked(args, waitMs = 300000) { const deadline = Date.now() + waitMs; while (true) { const code = await run(args); if (code !== 2 || Date.now() >= deadline) return code; await wait(250); } }
+if (command === 'route') {
+  const messageIndex = rest.indexOf('--message'); const message = messageIndex >= 0 ? String(rest[messageIndex + 1] || '') : '';
+  const amendment = /(?:继续(?:当前|这个)?\\s*loop|给(?:当前|这个)?\\s*loop\\s*(?:补充|增加|加)|补充当前\\s*loop)/i.test(message);
+  const routeCode = await run(['route-message', '--queue', ${JSON.stringify(queue)}, '--route', '--confirm-execute', amendment ? '--amend-active' : '--supersede-active', ...rest]);
+  const queueOnly = /(?:只入队|只排队|暂不执行|不立即执行)/.test(message);
+  const runCode = routeCode || queueOnly || amendment ? routeCode : await runWhenUnlocked(['run-queue', '--config', ${JSON.stringify(`configs/loops/queues/${queue}.json`)}, '--progress-notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  const humanCode = await run(['queue-human-input-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  const terminalCode = await run(['queue-terminal-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  process.exitCode = routeCode || runCode || humanCode || terminalCode;
+} else if (command === 'run-once') {
+  const runCode = await run(['run-queue', '--config', ${JSON.stringify(`configs/loops/queues/${queue}.json`)}, '--progress-notify-command', 'node scripts/loops/hermes-loop-notify.mjs', ...rest]);
+  const humanCode = await run(['queue-human-input-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  const terminalCode = await run(['queue-terminal-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  process.exitCode = runCode || humanCode || terminalCode;
+} 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/hermes-loop-notify.mjs', ...rest]);
+  const humanCode = await run(['queue-human-input-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  const terminalCode = await run(['queue-terminal-notify', '--queue', ${JSON.stringify(queue)}, '--notify-command', 'node scripts/loops/hermes-loop-notify.mjs']);
+  process.exitCode = tickCode || humanCode || terminalCode;
+} else { console.error('Usage: node scripts/loops/hermes-loop.mjs route|run-once|scheduler-tick'); process.exitCode = 1; }
+`;
+}
+
+function notifierSource({ hermesBin }) {
+  return `#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+const message = process.argv.slice(2).join(' ').trim();
+const rawSource = process.env.LOOP_HUMAN_INPUT_SOURCE || process.env.LOOP_NOTIFICATION_SOURCE || '';
+if (!message) { console.error('loop notifier requires a message'); process.exit(2); }
+let source; try { source = JSON.parse(rawSource); } catch { console.error('loop notifier received invalid source metadata'); process.exit(2); }
+if (!source || typeof source !== 'object' || !source.target) { console.error('Hermes loop notifier requires source.target in platform[:chat[:thread]] form'); process.exit(2); }
+const args = ['send', '--to', String(source.target), '--quiet', message];
+if (process.env.LOOP_NOTIFICATION_DRY_RUN === '1') { console.log(JSON.stringify({ dryRun: true, command: ${JSON.stringify(hermesBin)}, args })); }
+else { const child = spawn(${JSON.stringify(hermesBin)}, args, { cwd: process.cwd(), env: process.env, stdio: 'inherit' }); child.on('close', (code, signal) => { process.exitCode = code ?? (signal ? 128 : 1); }); }
+`;
+}
+
+function schedulerServiceSource({ root, queue }) { return `[Unit]\nDescription=Taskforce Loop Engineering Hermes scheduler for ${queue}\nAfter=default.target\n\n[Service]\nType=oneshot\nWorkingDirectory=${systemdEscapePath(root)}\nExecStart=${systemdEscapePath(process.execPath)} ${systemdEscapePath(path.join(root, 'scripts', 'loops', 'hermes-loop.mjs'))} scheduler-tick --json\n`; }
+function schedulerTimerSource({ queue }) { return `[Unit]\nDescription=Wake Taskforce Loop Engineering Hermes scheduler for ${queue}\n\n[Timer]\nOnBootSec=30s\nOnUnitActiveSec=1min\nAccuracySec=10s\nPersistent=true\nUnit=hermes-loop-${queue}-scheduler.service\n\n[Install]\nWantedBy=timers.target\n`; }
+function instructionsBlock({ queue }) { return `\n<!-- loop-engineering:hermes:start -->\n## Loop Engineering conversation routing (Hermes)\n\n- Route only explicit Loop Engineering requests. Already managed tasks must never be routed again.\n- Run \`node scripts/loops/hermes-loop.mjs route --message "<full user message>"\` and pass \`--source-channel <platform> --source-target <platform:chat_id[:thread_id]>\` so notifications return to the originating Hermes conversation.\n- \`走 loop\` executes immediately; only \`只入队\` or \`只排队\` suppresses execution. External, destructive, production, credential, or memory migration actions remain separately gated.\n- Queue: \`${queue}\`.\n<!-- loop-engineering:hermes:end -->\n`; }
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log('Usage: loop-engineering-hermes-install [--root workspace] [--queue agent-tasks] [--hermes-bin hermes] [--systemctl-bin systemctl] [--confirm-install] [--force] [--json]'); return; }
+  safeId(args.queue, 'queue');
+  args.hermesBin = await resolveExecutable(args.hermesBin);
+  const hermes = await run(args.hermesBin, ['--version'], { cwd: args.root });
+  if (hermes.code !== 0) throw new Error(`Cannot run Hermes CLI with ${args.hermesBin}: ${(hermes.stderr || hermes.stdout).trim() || `exit ${hermes.code}`}`);
+  const 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 unit = `hermes-loop-${args.queue}-scheduler.service`; const timer = `hermes-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`), dispatcher: path.join(args.root, 'scripts/loops/hermes-loop-dispatch.mjs'), wrapper: path.join(args.root, 'scripts/loops/hermes-loop.mjs'), notifier: path.join(args.root, 'scripts/loops/hermes-loop-notify.mjs'), manifest: path.join(args.root, 'runtime/loop-engineering-hermes-install.json'), instructions: path.join(args.root, 'AGENTS.md'), schedulerService: path.join(systemdUserDir, unit), schedulerTimer: path.join(systemdUserDir, timer) };
+  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 confirmationSummary = { targetPlatform: 'Hermes', platformCli: args.hermesBin, workspace: args.root, queue: args.queue, scheduler: `systemd user timer ${timer}`, notificationTarget: 'source-bound at runtime (original Hermes conversation)', writesEnabled: args.confirmInstall };
+  const report = { version: 1, platform: 'hermes', status: args.confirmInstall ? 'installed' : 'plan_only', readOnly: !args.confirmInstall, root: args.root, queue: args.queue, hermesBin: args.hermesBin, hermesVersion: (hermes.stdout || hermes.stderr).trim().slice(0, 200), scheduler: { required: true, unit, timer }, confirmationSummary, files: Object.fromEntries(Object.entries(files).map(([key, file]) => [key, path.relative(args.root, file)])), conflicts };
+  if (conflicts.length && !args.force && args.confirmInstall) throw new Error(`Refusing to overwrite: ${conflicts.join(', ')}. Use --force after review.`);
+  if (!args.json) console.log(formatConfirmationSummary(confirmationSummary));
+  if (args.confirmInstall) {
+    await mkdir(path.dirname(files.queueConfig), { recursive: true }); await mkdir(path.dirname(files.dispatcher), { recursive: true }); await mkdir(path.join(args.root, 'runtime', 'loops', args.queue), { recursive: true });
+    if (!await exists(files.workspaceHealth)) await writeFile(files.workspaceHealth, `${JSON.stringify({ id: 'workspace-health', goal: 'Keep this workspace loop-ready and detect obvious drift.', level: 'L1', mode: 'report-only', maxRuntimeMs: 120000, breaker: { maxConsecutiveFailures: 3, sameFailureThreshold: 2 }, checks: [{ id: 'workspace-root', type: 'files', paths: ['.'] }] }, null, 2)}\n`);
+    const queueContent = `${JSON.stringify({ queue: args.queue, description: 'Hermes conversation queue.', dispatcher: 'node scripts/loops/hermes-loop-dispatch.mjs', preflightConfig: 'configs/loops/workspace-health.json', timeoutMs: 1800000, leaseMs: 1860000, staleActiveMs: 3600000, 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 contents = { queueConfig: queueContent, dispatcher: dispatcherSource(args), wrapper: wrapperSource({ queue: args.queue, loopBin }), notifier: notifierSource(args), schedulerService: schedulerServiceSource({ root: args.root, queue: args.queue }), schedulerTimer: schedulerTimerSource({ queue: args.queue }) };
+    await mkdir(systemdUserDir, { recursive: true });
+    for (const [kind, content] of Object.entries(contents)) await writeFile(files[kind], content);
+    const reload = await run(args.systemctlBin, ['--user', 'daemon-reload'], { cwd: args.root }); if (reload.code !== 0) throw new Error(`Cannot reload user systemd units: ${(reload.stderr || reload.stdout).trim()}`);
+    const enable = await run(args.systemctlBin, ['--user', 'enable', '--now', timer], { cwd: args.root }); if (enable.code !== 0) throw new Error(`Cannot enable Hermes Loop scheduler ${timer}: ${(enable.stderr || enable.stdout).trim()}`);
+    const marker = instructionsBlock({ queue: args.queue }); const current = await readFile(files.instructions, 'utf8').catch(() => ''); if (!current.includes('<!-- loop-engineering:hermes:start -->')) await appendFile(files.instructions, marker);
+    await mkdir(path.dirname(files.manifest), { recursive: true }); await writeFile(files.manifest, `${JSON.stringify({ version: 1, platform: 'hermes', installedAt: new Date().toISOString(), root: args.root, queue: args.queue, hermesBin: args.hermesBin, files: Object.entries(contents).map(([kind, content]) => ({ kind, path: files[kind], sha256: sha256(content) })), scheduler: { unit, timer } }, null, 2)}\n`);
+  }
+  console.log(args.json ? JSON.stringify(report, null, 2) : `Hermes Loop installer: ${report.status}\nnext: ${args.confirmInstall ? 'Run loop-engineering-hermes-doctor, then route a harmless smoke task.' : 'Review this summary, then rerun with --confirm-install.'}`);
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/scripts/hermes-smoke.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const out = { root: process.cwd(), queue: 'agent-tasks', hermesBin: 'hermes', loopBin: 'loop-engineering', json: false, keepArtifacts: 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 === '--hermes-bin') out.hermesBin = argv[++i]; else if (arg === '--loop-bin') out.loopBin = argv[++i]; else if (arg === '--keep-artifacts') out.keepArtifacts = true; else if (arg === '--json') out.json = true; else if (arg === '--help' || arg === '-h') out.help = true; else throw new Error(`Unknown argument: ${arg}`); }
+  return out;
+}
+function run(command, args, options = {}) { return new Promise((resolve) => { const child = spawn(command, args, { cwd: options.cwd, env: options.env || process.env, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.stderr.on('data', (chunk) => { stderr += chunk; }); child.on('error', (error) => resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` })); child.on('close', (code, signal) => resolve({ code: code ?? (signal ? 128 : 1), stdout, stderr })); }); }
+async function exists(file) { try { await access(file); return true; } catch { return false; } }
+function safeId(value) { if (!/^[a-zA-Z0-9._-]+$/.test(value)) throw new Error('queue contains unsupported characters.'); return value; }
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log('Usage: loop-engineering-hermes-smoke [--root workspace] [--queue agent-tasks] [--hermes-bin hermes] [--loop-bin loop-engineering] [--keep-artifacts] [--json]'); return; }
+  safeId(args.queue); const runToken = `${Date.now()}-${process.pid}`; const smokeQueue = `smoke-${args.queue}-${runToken}`;
+  const baseConfig = path.join(args.root, `configs/loops/queues/${args.queue}.json`); const smokeConfig = path.join(args.root, `configs/loops/queues/${smokeQueue}.json`); const smokeRuntime = path.join(args.root, 'runtime', 'loops', smokeQueue); const doctorScript = new URL('./hermes-doctor.mjs', import.meta.url).pathname;
+  const steps = []; let taskId = null;
+  try {
+    const doctor = await run(process.execPath, [doctorScript, '--root', args.root, '--queue', args.queue, '--hermes-bin', args.hermesBin, '--json'], { cwd: args.root }); steps.push({ id: 'doctor', ok: doctor.code === 0 }); if (doctor.code !== 0) throw new Error(`doctor failed: ${doctor.stderr || doctor.stdout}`);
+    const config = JSON.parse(await readFile(baseConfig, 'utf8')); config.queue = smokeQueue; config.description = 'Temporary read-only Hermes integration smoke queue.'; config.retry = { ...(config.retry || {}), maxAttempts: 1 }; await mkdir(path.dirname(smokeConfig), { recursive: true }); await writeFile(smokeConfig, `${JSON.stringify(config, null, 2)}\n`);
+    const message = '走 loop：Perform a read-only Hermes integration smoke. Do not change files or external state. Report SMOKE_OK with verification evidence.';
+    const route = await run(args.loopBin, ['route-message', '--root', args.root, '--queue', smokeQueue, '--message', message, '--route', '--confirm-execute', '--source-channel', 'telegram', '--source-target', 'telegram:loop-smoke-dry-run', '--source-message-id', `smoke-${runToken}`, '--json'], { cwd: args.root }); steps.push({ id: 'route', ok: route.code === 0 }); if (route.code !== 0) throw new Error(`route failed: ${route.stderr || route.stdout}`);
+    taskId = JSON.parse(route.stdout).task?.id || null;
+    const execute = await run(args.loopBin, ['run-queue', '--root', args.root, '--config', path.relative(args.root, smokeConfig), '--json'], { cwd: args.root }); steps.push({ id: 'worker_execution', ok: execute.code === 0 }); if (execute.code !== 0) throw new Error(`worker execution failed: ${execute.stderr || execute.stdout}`);
+    const taskDir = taskId ? path.join(smokeRuntime, 'tasks', taskId) : '';
+    for (const artifact of ['task_contract.json', 'dev_plan.json', 'acceptance_plan.json', 'final_judgement.json']) { const ok = Boolean(taskDir) && await exists(path.join(taskDir, artifact)); steps.push({ id: `artifact:${artifact}`, ok }); if (!ok) throw new Error(`missing smoke artifact: ${artifact}`); }
+    const notifyEnv = { ...process.env, LOOP_NOTIFICATION_DRY_RUN: '1' }; const notifyCommand = 'node scripts/loops/hermes-loop-notify.mjs';
+    const humanNotify = await run(args.loopBin, ['queue-human-input-notify', '--root', args.root, '--queue', smokeQueue, '--notify-command', notifyCommand, '--json'], { cwd: args.root, env: notifyEnv }); steps.push({ id: 'human_gate_scan', ok: humanNotify.code === 0 });
+    const terminalNotify = await run(args.loopBin, ['queue-terminal-notify', '--root', args.root, '--queue', smokeQueue, '--notify-command', notifyCommand, '--json'], { cwd: args.root, env: notifyEnv }); const terminal = terminalNotify.code === 0 ? JSON.parse(terminalNotify.stdout) : null; const terminalOk = terminalNotify.code === 0 && terminal?.sent === 1; steps.push({ id: 'terminal_dry_run_return', ok: terminalOk }); if (!terminalOk) throw new Error(`terminal dry-run failed: ${terminalNotify.stderr || terminalNotify.stdout}`);
+    const report = { version: 1, platform: 'hermes', status: 'ok', readOnlyTask: true, externalWrite: false, queue: args.queue, smokeQueue, taskId, steps, keptArtifacts: args.keepArtifacts };
+    console.log(args.json ? JSON.stringify(report, null, 2) : `Hermes Loop smoke: ok\ntask: ${taskId}\nexternal write: no\nartifacts: ${args.keepArtifacts ? smokeRuntime : 'cleaned'}`);
+  } finally { if (!args.keepArtifacts && smokeQueue.startsWith(`smoke-${args.queue}-`)) { await rm(smokeConfig, { force: true }); await rm(smokeRuntime, { recursive: true, force: true }); } }
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

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

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
-const root = await mkdtemp(path.join(tmpdir(), 'loop-openclaw-install-'));
+const root = await mkdtemp(path.join(tmpdir(), 'loop openclaw 安装-'));
 const deliveryCapture = path.join(root, 'delivery.json');
 const mockOpenClaw = path.join(root, 'mock-openclaw.mjs');
 const mockSystemctl = path.join(root, 'mock-systemctl.mjs');
@@ -46,7 +46,9 @@ function run(args) {
 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}`);
+if (plan.code !== 0 || planReport.status !== 'plan_only' || planReport.platform !== 'openclaw' || planReport.workerAgent !== 'builder' || planReport.workerSelection !== 'only_available' || !planReport.workerValidated || planReport.createsWorkerAgent || planReport.confirmationSummary?.targetPlatform !== 'OpenClaw' || planReport.confirmationSummary?.writesEnabled !== false || !path.isAbsolute(planReport.confirmationSummary?.platformCli || '') || !planReport.confirmationSummary?.notificationTarget.includes('OpenClaw')) throw new Error(`plan failed: ${plan.stderr}`);
+const humanPlan = await run(installBase);
+if (humanPlan.code !== 0 || !humanPlan.stdout.includes('Installation confirmation') || !humanPlan.stdout.includes('target platform: OpenClaw') || !humanPlan.stdout.includes('writes enabled: no (plan only)')) throw new Error('human-readable OpenClaw confirmation summary missing');
 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([...installBase, '--worker-agent', 'builder', '--confirm-install', '--json']);
@@ -66,6 +68,14 @@ const timerFile = path.join(process.env.XDG_CONFIG_HOME, 'systemd/user/openclaw-
 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');
+if (service.includes('WorkingDirectory="') || service.includes('ExecStart="') || !service.includes('\\x20') || !service.includes('\\xe5\\xae\\x89\\xe8\\xa3\\x85')) throw new Error('scheduler service paths were not encoded with systemd path escapes');
+const systemdVerify = await new Promise((resolve) => {
+  const child = spawn('systemd-analyze', ['verify', serviceFile, timerFile], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = ''; let stderr = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.on('error', (error) => resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` }));
+  child.on('close', (code) => resolve({ code, stdout, stderr }));
+});
+if (systemdVerify.code !== 0) throw new Error(`systemd rejected generated scheduler units: ${systemdVerify.stderr || systemdVerify.stdout}`);
 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) => {

package/scripts/openclaw-install.mjs

@@ -22,8 +22,12 @@ function parseArgs(argv) {
   return out;
 }
 
-function systemdEscape(value) {
-  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+function systemdEscapePath(value) {
+  return [...Buffer.from(String(value))]
+    .map((byte) => /[A-Za-z0-9/_.:-]/.test(String.fromCharCode(byte))
+      ? String.fromCharCode(byte)
+      : `\\x${byte.toString(16).padStart(2, '0')}`)
+    .join('');
 }
 
 function safeId(value, label) {
@@ -63,6 +67,32 @@ async function exists(file) {
   try { await access(file); return true; } catch { return false; }
 }
 
+async function resolveExecutable(command) {
+  if (path.isAbsolute(command) || command.includes(path.sep)) {
+    const resolved = path.resolve(command);
+    if (!await exists(resolved)) throw new Error(`Executable not found: ${resolved}`);
+    return resolved;
+  }
+  for (const dir of String(process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, command);
+    if (await exists(candidate)) return candidate;
+  }
+  throw new Error(`Executable not found on PATH: ${command}`);
+}
+
+function formatConfirmationSummary(summary) {
+  return [
+    'Installation confirmation',
+    `  target platform: ${summary.targetPlatform}`,
+    `  platform CLI: ${summary.platformCli}`,
+    `  workspace: ${summary.workspace}`,
+    `  queue: ${summary.queue}`,
+    `  scheduler: ${summary.scheduler}`,
+    `  notification target: ${summary.notificationTarget}`,
+    `  writes enabled: ${summary.writesEnabled ? 'yes' : 'no (plan only)'}`
+  ].join('\n');
+}
+
 function dispatcherSource({ workerAgent, openclawBin }) {
   return `#!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
@@ -140,7 +170,7 @@ 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`;
+  return `[Unit]\nDescription=Taskforce Loop Engineering scheduler for ${queue}\nAfter=default.target\n\n[Service]\nType=oneshot\nWorkingDirectory=${systemdEscapePath(root)}\nExecStart=${systemdEscapePath(process.execPath)} ${systemdEscapePath(path.join(root, 'scripts', 'loops', 'openclaw-loop.mjs'))} scheduler-tick --json\n`;
 }
 
 function schedulerTimerSource({ queue }) {
@@ -188,6 +218,7 @@ async function main() {
   }
   safeId(args.queue, 'queue');
   if (args.workerAgent) safeId(args.workerAgent, 'worker agent');
+  args.openclawBin = await resolveExecutable(args.openclawBin);
   const worker = await resolveWorkerAgent(args);
   args.workerAgent = worker.workerAgent;
   args.loopBin = new URL('../bin/loop-engineering.mjs', import.meta.url).pathname;
@@ -207,9 +238,11 @@ async function main() {
   };
   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, 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 };
+  const confirmationSummary = { targetPlatform: 'OpenClaw', platformCli: args.openclawBin, workspace: args.root, queue: args.queue, scheduler: `systemd user timer ${schedulerTimer}`, notificationTarget: 'source-bound at runtime (original OpenClaw conversation)', writesEnabled: args.confirmInstall };
+  const report = { version: 1, platform: 'openclaw', 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 }, confirmationSummary, 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.json) console.log(formatConfirmationSummary(confirmationSummary));
   if (args.confirmInstall) {
     await mkdir(path.dirname(files.queueConfig), { recursive: true });
     await mkdir(path.dirname(files.dispatcher), { recursive: true });
@@ -268,7 +301,7 @@ async function main() {
       retainedOnUninstall: [`runtime/loops/${args.queue}`]
     }, null, 2)}\n`);
   }
-  console.log(args.json ? JSON.stringify(report, null, 2) : `OpenClaw integration: ${report.status}\nqueue: ${report.queue}\nworker: ${report.workerAgent}\nconflicts: ${report.conflicts.join(', ') || 'none'}\nnext: ${report.next}`);
+  console.log(args.json ? JSON.stringify(report, null, 2) : `OpenClaw integration: ${report.status}\nconflicts: ${report.conflicts.join(', ') || 'none'}\nnext: ${report.next}`);
 }
 
 main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

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

@@ -11,7 +11,7 @@ Do not route ordinary chat, research, explanations, or simple direct tasks into
 
 ## Distribution and CLI Installation
 
-A ClawHub installation may provide only this `SKILL.md`; it does **not** prove that the Loop Engineering CLI or OpenClaw integration is installed. Before running loop commands, check the deployment explicitly:
+A skill installation may provide only this `SKILL.md`; it does **not** prove that the Loop Engineering CLI or an OpenClaw/Hermes integration is installed. Before running loop commands, check the deployment explicitly:
 
 ```bash
 command -v loop-engineering
@@ -62,7 +62,7 @@ loop-engineering-openclaw-install \
   --queue agent-tasks
 ```
 
-Review the detected agents and planned files. Then install with an existing worker-agent id:
+Review the installation confirmation summary before proceeding. It must show the target platform, absolute platform CLI path, workspace, queue, scheduler, notification routing, and `writes enabled: no (plan only)`. If any field identifies the wrong platform or destination, stop. Then install with an existing worker-agent id:
 
 ```bash
 loop-engineering-openclaw-install \
@@ -88,6 +88,34 @@ loop-engineering-openclaw-smoke \
 
 If the CLI or integration is missing and the user requested installation or repair, install it within the authorized host/workspace scope, then run doctor and the disposable smoke. If the user only asked what is missing, report the exact package, repository, commands, and current deployment state without mutating the system.
 
+### Hermes Agent Integration
+
+The core CLI is platform-neutral, but Hermes conversation routing requires its own dispatcher and notifier. Generate a plan and verify its installation confirmation summary identifies Hermes, the absolute Hermes CLI path, intended workspace and queue, systemd scheduler, source-bound notification routing, and `writes enabled: no (plan only)`. If any field identifies the wrong platform or destination, stop. Confirm installation only after that review, then run the read-only doctor and disposable smoke:
+
+```bash
+loop-engineering-hermes-install \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+
+loop-engineering-hermes-install \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks \
+  --confirm-install
+
+loop-engineering-hermes-doctor \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+
+loop-engineering-hermes-smoke \
+  --root /path/to/hermes/workspace \
+  --queue agent-tasks
+```
+
+The generated worker uses `hermes -z` (`--oneshot`); the notifier uses `hermes send` without
+an LLM call. Preserve source metadata and pass `--source-target` in Hermes
+`platform:chat_id[:thread_id]` format. The managed systemd scheduler owns wakeups
+so durable queue continuity does not depend on resuming a Hermes Cron session.
+
 ## Conversation Contract
 
 Interpret explicit loop language as follows:

package/skills/taskforce-loop-engineering/references/npm-package.md

@@ -1,7 +1,7 @@
 # npm Package
 
 Package name: `taskforce-loop-engineering`
-Version: `0.7.0`
+Version: `0.9.0`
 
 Install from npm:
 
@@ -9,6 +9,15 @@ Install from npm:
 npm install -g taskforce-loop-engineering
 ```
 
+Hermes Agent integration commands:
+
+```bash
+loop-engineering-hermes-install --root /path/to/hermes/workspace --queue agent-tasks
+loop-engineering-hermes-install --root /path/to/hermes/workspace --queue agent-tasks --confirm-install
+loop-engineering-hermes-doctor --root /path/to/hermes/workspace --queue agent-tasks
+loop-engineering-hermes-smoke --root /path/to/hermes/workspace --queue agent-tasks
+```
+
 Installed commands:
 
 ```bash