taskforce-loop-engineering 0.7.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "taskforce-loop-engineering",
+  "version": "0.7.0",
+  "private": false,
+  "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
+  "type": "module",
+  "bin": {
+    "loop-engineering": "bin/loop-engineering.mjs",
+    "agent-loop": "bin/loop-engineering.mjs",
+    "loop-engineering-openclaw-install": "scripts/openclaw-install.mjs",
+    "loop-engineering-openclaw-doctor": "scripts/openclaw-doctor.mjs",
+    "loop-engineering-openclaw-smoke": "scripts/openclaw-smoke.mjs",
+    "loop-engineering-openclaw-manage": "scripts/openclaw-manage.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/route-notify-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "MIGRATING.md",
+    "README.md",
+    "bin/",
+    "lib/",
+    "scripts/",
+    "templates/",
+    "skills/taskforce-loop-engineering/"
+  ],
+  "keywords": [
+    "openclaw",
+    "agent",
+    "taskforce-loop-engineering",
+    "loop-engineering",
+    "automation",
+    "cron",
+    "health-check"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambitioncn/taskforce-loop-engineering.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ambitioncn/taskforce-loop-engineering/issues"
+  },
+  "homepage": "https://github.com/ambitioncn/taskforce-loop-engineering#readme",
+  "license": "Apache-2.0"
+}

package/scripts/config-drift-self-test.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { loopRepairPlan, runCheck, validateSpec } from '../lib/core.mjs';
+
+const root = await mkdtemp(path.join(tmpdir(), 'loop-config-drift-'));
+await writeFile(path.join(root, 'config.json'), `${JSON.stringify({ model: 'new-model' })}\n`);
+const check = { id: 'default-model', type: 'json-value', file: 'config.json', pointer: '/model', expected: 'old-model' };
+validateSpec({ id: 'config-drift-smoke', goal: 'Detect explainable configuration drift.', level: 'L1', mode: 'report-only', checks: [check] });
+const result = await runCheck(root, check);
+assert.equal(result.ok, false);
+assert.equal(result.expected, 'old-model');
+assert.equal(result.actual, 'new-model');
+assert.equal(result.drift.kind, 'configuration_value_mismatch');
+const plan = loopRepairPlan({ loopId: 'config-drift-smoke', outcome: 'failure', runPath: 'example.json', checks: [result] });
+assert.equal(plan.status, 'review_required');
+assert.equal(plan.readOnly, true);
+assert.equal(plan.autoApply, false);
+assert.equal(plan.findings[0].actual, 'new-model');
+console.log('config drift self-test passed');

package/scripts/openclaw-doctor.mjs

@@ -0,0 +1,77 @@
+#!/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', workerAgent: 'main', openclawBin: 'openclaw', 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 === '--worker-agent') out.workerAgent = argv[++i];
+    else if (arg === '--openclaw-bin') out.openclawBin = 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-openclaw-doctor [--root workspace] [--queue agent-tasks] [--worker-agent main] [--openclaw-bin openclaw] [--json]');
+    return;
+  }
+  const required = [
+    `configs/loops/queues/${args.queue}.json`,
+    'configs/loops/workspace-health.json',
+    'scripts/loops/openclaw-loop-dispatch.mjs',
+    'scripts/loops/openclaw-loop.mjs',
+    'scripts/loops/openclaw-loop-notify.mjs',
+    '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.openclawBin, ['--version'], { cwd: args.root });
+  checks.push({ id: 'openclaw_cli', ok: cli.code === 0, detail: (cli.stdout || cli.stderr).trim().slice(0, 300) });
+  const agentsResult = await run(args.openclawBin, ['agents', 'list', '--json'], { cwd: args.root });
+  let agents = [];
+  try { agents = JSON.parse(agentsResult.stdout); } catch { /* reported below */ }
+  checks.push({ id: 'worker_agent', ok: agentsResult.code === 0 && Array.isArray(agents) && agents.some((agent) => agent?.id === args.workerAgent), detail: args.workerAgent });
+  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/openclaw-loop-dispatch.mjs' });
+    } catch (error) { checks.push({ id: 'queue_config', ok: false, detail: error.message }); }
+  }
+  const notifier = path.join(args.root, 'scripts/loops/openclaw-loop-notify.mjs');
+  if (await present(notifier)) {
+    const smoke = 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: 'feishu', target: 'user:loop-doctor-dry-run', account: 'doctor', reply_to: 'doctor-message' }) }
+    });
+    checks.push({ id: 'notification_dry_run', ok: smoke.code === 0, detail: (smoke.stdout || smoke.stderr).trim().slice(0, 500) });
+  }
+  const failed = checks.filter((check) => !check.ok);
+  const report = { version: 1, status: failed.length ? 'fail' : 'ok', readOnly: true, externalWrite: false, root: args.root, queue: args.queue, workerAgent: args.workerAgent, checks, failed: failed.map((check) => check.id) };
+  console.log(args.json ? JSON.stringify(report, null, 2) : `OpenClaw 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/openclaw-install-self-test.mjs

@@ -0,0 +1,129 @@
+#!/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-openclaw-install-'));
+const deliveryCapture = path.join(root, 'delivery.json');
+const mockOpenClaw = path.join(root, 'mock-openclaw.mjs');
+await writeFile(mockOpenClaw, `#!/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('OpenClaw mock 1.0');
+else if (args[0] === 'agents' && args[1] === 'list') console.log(JSON.stringify([{ id: 'builder' }]));
+else {
+  if (args[0] === 'agent' && 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: 'Read-only smoke completed.', files_changed: [], verification: [{ command: 'mock smoke', outcome: 'passed' }], blockers: [], risks: [], next_action: 'acceptance_review' }));
+  }
+  if (process.env.DELIVERY_CAPTURE) await writeFile(process.env.DELIVERY_CAPTURE, JSON.stringify(args));
+  console.log(JSON.stringify({ ok: true, dryRun: args.includes('--dry-run') }));
+}
+`);
+await chmod(mockOpenClaw, 0o755);
+const installer = new URL('./openclaw-install.mjs', import.meta.url).pathname;
+function run(args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [installer, ...args], { 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 plan = await run(['--root', root, '--queue', 'test-tasks', '--openclaw-bin', mockOpenClaw, '--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']);
+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']);
+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');
+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');
+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');
+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) => {
+  const child = spawn(process.execPath, [path.join(root, 'scripts/loops/openclaw-loop-notify.mjs'), 'async result'], {
+    cwd: root,
+    env: { ...process.env, DELIVERY_CAPTURE: deliveryCapture, LOOP_NOTIFICATION_SOURCE: JSON.stringify({ channel: 'slack', target: 'channel:C123', account: 'work', reply_to: 'M456' }) },
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  let stderr = ''; child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.on('close', (code) => resolve({ code, stderr }));
+});
+if (delivery.code !== 0) throw new Error(`notifier delivery failed: ${delivery.stderr}`);
+const deliveredArgs = JSON.parse(await readFile(deliveryCapture, 'utf8'));
+for (const expected of ['message', 'send', '--channel', 'slack', '--target', 'channel:C123', '--account', 'work', '--reply-to', 'M456', 'async result']) {
+  if (!deliveredArgs.includes(expected)) throw new Error(`notifier did not forward ${expected}`);
+}
+const doctor = new URL('./openclaw-doctor.mjs', import.meta.url).pathname;
+const doctorResult = await new Promise((resolve) => {
+  const child = spawn(process.execPath, [doctor, '--root', root, '--queue', 'test-tasks', '--worker-agent', 'builder', '--openclaw-bin', mockOpenClaw, '--json'], { 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 (doctorResult.code !== 0) throw new Error(`doctor failed: ${doctorResult.stderr}`);
+const doctorReport = JSON.parse(doctorResult.stdout);
+if (doctorReport.status !== 'ok' || doctorReport.externalWrite !== false || !doctorReport.checks.some((check) => check.id === 'notification_dry_run' && check.ok)) throw new Error('doctor did not complete a safe notification dry-run');
+const smoke = new URL('./openclaw-smoke.mjs', import.meta.url).pathname;
+const loopBin = new URL('../bin/loop-engineering.mjs', import.meta.url).pathname;
+const smokeResult = await new Promise((resolve) => {
+  const child = spawn(process.execPath, [smoke, '--root', root, '--queue', 'test-tasks', '--worker-agent', 'builder', '--openclaw-bin', mockOpenClaw, '--loop-bin', loopBin, '--json'], { 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 (smokeResult.code !== 0) throw new Error(`smoke failed: ${smokeResult.stderr}`);
+const smokeReport = JSON.parse(smokeResult.stdout);
+if (smokeReport.status !== 'ok' || smokeReport.externalWrite !== false || !smokeReport.steps.every((step) => step.ok)) throw new Error('end-to-end smoke did not pass safely');
+try { await readFile(path.join(root, `configs/loops/queues/${smokeReport.smokeQueue}.json`)); throw new Error('smoke config was not cleaned'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+try { await readFile(path.join(root, `runtime/loops/${smokeReport.smokeQueue}/state.json`)); throw new Error('smoke runtime was not cleaned'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+for (const generated of ['scripts/loops/openclaw-loop-dispatch.mjs', 'scripts/loops/openclaw-loop.mjs', 'scripts/loops/openclaw-loop-notify.mjs']) {
+  const syntax = await run(['--help']);
+  if (syntax.code !== 0) throw new Error(`installer help failed while checking ${generated}`);
+  const check = await new Promise((resolve) => {
+    const child = spawn(process.execPath, ['--check', path.join(root, generated)], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stderr = ''; child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('close', (code) => resolve({ code, stderr }));
+  });
+  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']);
+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) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [manager, '--root', root, ...args, '--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 }));
+  });
+}
+await writeFile(path.join(root, 'scripts/loops/openclaw-loop.mjs'), `${wrapper}\n// local edit\n`);
+const modifiedPlan = await manage(['--action', 'uninstall-plan']);
+if (modifiedPlan.code !== 0 || JSON.parse(modifiedPlan.stdout).status !== 'review_required') throw new Error('modified managed file was not detected');
+const refusedUninstall = await manage(['--action', 'uninstall', '--confirm-uninstall']);
+if (refusedUninstall.code === 0) throw new Error('uninstall removed modified managed content');
+await writeFile(path.join(root, 'scripts/loops/openclaw-loop.mjs'), wrapper);
+const upgradePlan = await manage(['--action', 'upgrade-plan']);
+if (upgradePlan.code !== 0 || JSON.parse(upgradePlan.stdout).status !== 'ready') throw new Error(`upgrade plan failed: ${upgradePlan.stderr}`);
+const upgrade = await manage(['--action', 'upgrade', '--confirm-upgrade']);
+if (upgrade.code !== 0 || JSON.parse(upgrade.stdout).status !== 'upgraded') throw new Error(`upgrade failed: ${upgrade.stderr}`);
+const uninstallPlan = await manage(['--action', 'uninstall-plan']);
+if (uninstallPlan.code !== 0 || JSON.parse(uninstallPlan.stdout).status !== 'ready') throw new Error(`uninstall plan failed: ${uninstallPlan.stderr}`);
+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');
+console.log('openclaw installer self-test passed');

package/scripts/openclaw-install.mjs

@@ -0,0 +1,235 @@
+#!/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', workerAgent: null, openclawBin: 'openclaw', 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 === '--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;
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+
+function run(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options.cwd, 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 resolveWorkerAgent(args) {
+  const result = await run(args.openclawBin, ['agents', 'list', '--json'], { cwd: args.root });
+  if (result.code !== 0) throw new Error(`Cannot inspect OpenClaw agents with ${args.openclawBin}: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+  let agents;
+  try { agents = JSON.parse(result.stdout); } catch { throw new Error('OpenClaw agents list did not return valid JSON.'); }
+  if (!Array.isArray(agents)) throw new Error('OpenClaw agents list did not return an array.');
+  const ids = agents.map((agent) => agent?.id).filter((id) => typeof id === 'string' && id);
+  if (args.workerAgent) {
+    if (!ids.includes(args.workerAgent)) throw new Error(`Worker agent ${args.workerAgent} does not exist. Available agents: ${ids.join(', ') || 'none'}. Create it first or choose an existing agent.`);
+    return { workerAgent: args.workerAgent, selection: 'explicit', availableAgents: ids };
+  }
+  if (ids.includes('main')) return { workerAgent: 'main', selection: 'default_main', availableAgents: ids };
+  if (ids.length === 1) return { workerAgent: ids[0], selection: 'only_available', availableAgents: ids };
+  throw new Error(`Cannot choose a worker agent automatically. Available agents: ${ids.join(', ') || 'none'}. Pass --worker-agent <id>; create the agent first if needed.`);
+}
+
+async function exists(file) {
+  try { await access(file); return true; } catch { return false; }
+}
+
+function dispatcherSource({ workerAgent, openclawBin }) {
+  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, even if its quoted request contains a loop trigger.',
+  'Read the task contract, development plan, and acceptance plan 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 writing each checkpoint and before final completion, reread the live amendment file if it exists. Treat every recorded amendment as part of the task contract and acceptance criteria.',
+  'Write a checkpoint when possible. Include the latest amendment_version applied. Finish with status, evidence, verification, blockers, and next action.'
+].join('\\n');
+const child = spawn(${JSON.stringify(openclawBin)}, [
+  'agent', '--agent', ${JSON.stringify(workerAgent)},
+  '--session-key', \`agent:${workerAgent}:loop-task-\${task.id}\`,
+  '--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 }) {
+  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' });
+    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 routeMode = amendment ? '--amend-active' : '--supersede-active';
+  const routeCode = await run(['route-message', '--queue', ${JSON.stringify(queue)}, '--route', '--confirm-execute', routeMode, ...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/openclaw-loop-notify.mjs']);
+  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 = routeCode || runCode || humanNotifyCode || terminalNotifyCode;
+} 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/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 = runCode || humanNotifyCode || terminalNotifyCode;
+} else {
+  console.error('Usage: node scripts/loops/openclaw-loop.mjs route --message "走 loop：任务" [source metadata]');
+  process.exitCode = 1;
+}
+`;
+}
+
+function notifierSource({ openclawBin }) {
+  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 argument.'); 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.channel || !source.target) {
+  console.error('loop notifier requires source.channel and source.target; refusing an unscoped delivery.');
+  process.exit(2);
+}
+const args = ['message', 'send', '--channel', String(source.channel), '--target', String(source.target), '--message', message, '--json'];
+if (source.account) args.push('--account', String(source.account));
+if (source.reply_to) args.push('--reply-to', String(source.reply_to));
+if (process.env.LOOP_NOTIFICATION_DRY_RUN === '1') args.push('--dry-run');
+const child = spawn(${JSON.stringify(openclawBin)}, args, { cwd: process.cwd(), env: process.env, stdio: 'inherit' });
+child.on('close', (code, signal) => { process.exitCode = code ?? (signal ? 128 : 1); });
+`;
+}
+
+function instructionsBlock({ queue }) {
+  return `\n<!-- loop-engineering:openclaw:start -->
+## Loop Engineering conversation routing
+
+- Route only explicit loop requests. \`走 loop\` means enqueue and immediately execute one tick; only \`只入队\` or \`只排队\` suppresses execution.
+- Run \`node scripts/loops/openclaw-loop.mjs route --message "<full user message>"\` from this workspace and preserve source metadata when available.
+- An already loop-managed task must be executed directly and never routed again.
+- Status questions are read-only. High-risk external, destructive, production, credential, or memory migration actions remain separately gated.
+- Queue: \`${queue}\`.
+<!-- loop-engineering:openclaw:end -->\n`;
+}
+
+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]');
+    return;
+  }
+  safeId(args.queue, 'queue');
+  if (args.workerAgent) safeId(args.workerAgent, 'worker agent');
+  const worker = await resolveWorkerAgent(args);
+  args.workerAgent = worker.workerAgent;
+  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', 'openclaw-loop-dispatch.mjs'),
+    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')
+  };
+  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 };
+  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) {
+    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: `OpenClaw conversation queue dispatched to agent ${args.workerAgent}.`,
+      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'] },
+      revisionPolicy: { enabled: true, maxRevisionRounds: 3, sameFailureThreshold: 2, requireStrategyChange: true }
+    }, null, 2)}\n`;
+    const dispatcherContent = dispatcherSource(args);
+    const wrapperContent = wrapperSource(args);
+    const notifierContent = notifierSource(args);
+    await writeFile(files.queueConfig, queueContent);
+    await writeFile(files.dispatcher, dispatcherContent);
+    await writeFile(files.wrapper, wrapperContent);
+    await writeFile(files.notifier, notifierContent);
+    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(),
+      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) }
+      ],
+      managedInstructions: { path: 'AGENTS.md', sha256: sha256(managedInstructions), content: managedInstructions },
+      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}`);
+}
+
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/scripts/openclaw-manage.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { access, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+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 parseArgs(argv) {
+  const out = { root: process.cwd(), action: 'uninstall-plan', json: false, confirm: 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 === '--action') out.action = argv[++i];
+    else if (arg === '--confirm-uninstall' || arg === '--confirm-upgrade') out.confirm = 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;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log('Usage: loop-engineering-openclaw-manage --action upgrade-plan|upgrade|uninstall-plan|uninstall [--root workspace] [--confirm-upgrade|--confirm-uninstall] [--json]'); return; }
+  if (!['upgrade-plan', 'upgrade', 'uninstall-plan', 'uninstall'].includes(args.action)) throw new Error('Unsupported action.');
+  if (args.action === 'uninstall' && !args.confirm) throw new Error('uninstall requires --confirm-uninstall.');
+  if (args.action === 'upgrade' && !args.confirm) throw new Error('upgrade requires --confirm-upgrade.');
+  const manifestFile = path.join(args.root, 'runtime', 'loop-engineering-openclaw-install.json');
+  if (!await exists(manifestFile)) throw new Error('OpenClaw integration manifest not found; refusing unmanaged removal.');
+  const manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+  const files = [];
+  for (const entry of manifest.managedFiles || []) {
+    const file = path.join(args.root, entry.path);
+    const present = await exists(file);
+    const current = present ? await readFile(file, 'utf8') : '';
+    files.push({ path: entry.path, 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 };
+  if (args.action === 'uninstall') {
+    if (!plan.ready) throw new Error(`Refusing uninstall because managed content changed: ${[...modified, ...(!instructionsClean ? ['AGENTS.md managed block'] : [])].join(', ')}`);
+    for (const item of files) if (item.present && item.clean) await rm(path.join(args.root, item.path), { force: true });
+    await writeFile(agentsFile, agentsText.replace(block, ''));
+    await rm(manifestFile, { force: true });
+    plan.status = 'uninstalled'; plan.readOnly = false;
+  } else if (args.action === 'upgrade') {
+    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'] });
+      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 }));
+    });
+    if (result.code !== 0) throw new Error(`upgrade installer failed: ${result.stderr || result.stdout}`);
+    plan.status = 'upgraded'; plan.readOnly = false;
+  } else plan.status = plan.ready ? 'ready' : 'review_required';
+  console.log(args.json ? JSON.stringify(plan, null, 2) : `OpenClaw integration ${args.action}: ${plan.status}\nmodified: ${modified.join(', ') || 'none'}\nretained: ${plan.retained.join(', ') || 'none'}`);
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });