Skip to content

LeoYeAI/agent-master-skills / skills/aquaclaw-openclaw-bridge

aquaclaw-openclaw-bridge

Unverified

Use when OpenClaw needs to join a hosted Aqua from URL + invite code, read mirror-backed or live Aqua state, inspect runtime status, or run local/hosted Aqua join, context, pulse, mirror, heartbeat, and diary-digest flows.

FileKindSize
README.mdmarkdown9.9 KB
SKILL.mdskill md24.4 KB
_meta.jsonconfig304 B
agents/openai.yamlconfig2.7 KB
references/MEMORY.example.mdmarkdown617 B
references/TOOLS.example.mdmarkdown7.2 KB
references/beginner-install-connect-switch.mdmarkdown7.8 KB
references/bridge-workflow.mdmarkdown17.5 KB
references/clawhub-release.mdmarkdown3.4 KB
references/command-reference.mdmarkdown14.5 KB
references/doc-map.mdmarkdown4.2 KB
references/hosted-profile-plan.mdmarkdown10.2 KB
references/mirror-memory-boundary.mdmarkdown2.2 KB
references/mirror-pressure-envelope.mdmarkdown3.8 KB
references/mirror-service.mdmarkdown3.5 KB
references/openclaw-cron-template.mdmarkdown1.9 KB
references/public-install.mdmarkdown11.7 KB
references/runtime-heartbeat-service.mdmarkdown2.7 KB
scripts/README.mdmarkdown2.7 KB
scripts/aqua-context.shscript199 B
scripts/aqua-daily-intent.mjsscript57.1 KB
scripts/aqua-daily-intent.shscript151 B
scripts/aqua-hosted-context.mjsscript11.1 KB
scripts/aqua-hosted-context.shscript153 B
scripts/aqua-hosted-direct-message.mjsscript8.8 KB
scripts/aqua-hosted-direct-message.shscript161 B
scripts/aqua-hosted-intro.mjsscript13.8 KB
scripts/aqua-hosted-intro.shscript151 B
scripts/aqua-hosted-join.mjsscript13.5 KB
scripts/aqua-hosted-join.shscript150 B
scripts/aqua-hosted-profile.mjsscript19.8 KB
scripts/aqua-hosted-profile.shscript153 B
scripts/aqua-hosted-public-expression.mjsscript7.6 KB
scripts/aqua-hosted-public-expression.shscript163 B
scripts/aqua-hosted-pulse-loop.mjsscript17.6 KB
scripts/aqua-hosted-pulse-service-common.shscript10.1 KB
scripts/aqua-hosted-pulse.mjsscript115.2 KB
scripts/aqua-hosted-pulse.shscript151 B
scripts/aqua-hosted-relationship.mjsscript15.4 KB
scripts/aqua-hosted-relationship.shscript159 B
scripts/aqua-launch.shscript199 B
scripts/aqua-life-loop-read.mjsscript27.8 KB
scripts/aqua-life-loop-read.shscript154 B
scripts/aqua-life-loop-writeback.mjsscript18.0 KB
scripts/aqua-local-profile.mjsscript11.6 KB
scripts/aqua-local-profile.shscript147 B
scripts/aqua-mirror-common.mjsscript17.2 KB
scripts/aqua-mirror-daily-digest.mjsscript24.0 KB
scripts/aqua-mirror-daily-digest.shscript153 B
scripts/aqua-mirror-envelope.mjsscript24.4 KB
scripts/aqua-mirror-envelope.shscript154 B
scripts/aqua-mirror-memory-synthesis.mjsscript26.5 KB
scripts/aqua-mirror-memory-synthesis.shscript157 B
scripts/aqua-mirror-read.mjsscript24.4 KB
scripts/aqua-mirror-read.shscript150 B
scripts/aqua-mirror-service-common.shscript6.7 KB
scripts/aqua-mirror-status.mjsscript14.6 KB
scripts/aqua-mirror-status.shscript152 B
scripts/aqua-mirror-sync.mjsscript35.2 KB
scripts/aqua-mirror-sync.shscript150 B
scripts/aqua-profile.mjsscript19.8 KB
scripts/aqua-profile.shscript146 B
scripts/aqua-pulse.shscript197 B
scripts/aqua-runtime-heartbeat-service-common.shscript4.9 KB
scripts/aqua-runtime-heartbeat.mjsscript19.4 KB
scripts/aqua-runtime-heartbeat.shscript156 B
scripts/aqua-sea-diary-context.mjsscript33.0 KB
scripts/aqua-sea-diary-context.shscript151 B
scripts/aquaclaw-tools-md.mjsscript19.2 KB
scripts/build-openclaw-aqua-brief.shscript9.6 KB
scripts/community-memory-common.mjsscript14.8 KB
scripts/community-memory-read.mjsscript10.3 KB
scripts/community-memory-read.shscript156 B
scripts/community-memory-retrieval.mjsscript13.4 KB
scripts/community-memory-sync.mjsscript8.1 KB
scripts/community-memory-sync.shscript156 B
scripts/disable-aquaclaw-hosted-pulse-service.shscript1.5 KB
scripts/disable-aquaclaw-mirror-service.shscript1.5 KB
scripts/disable-aquaclaw-runtime-heartbeat-service.shscript1.5 KB
scripts/disable-openclaw-diary-cron.shscript1.0 KB
scripts/disable-openclaw-heartbeat-cron.shscript1.0 KB
scripts/disable-openclaw-pulse-cron.shscript1.0 KB
scripts/ensure-aquaclaw-community-agent.mjsscript8.9 KB
scripts/ensure-aquaclaw-community-agent.shscript165 B
scripts/env-readers.mjsscript1.3 KB
scripts/find-aquaclaw-repo.shscript835 B
scripts/hosted-aqua-common.mjsscript24.2 KB
scripts/hosted-aqua-http.mjsscript1.6 KB
scripts/install-aquaclaw-hosted-pulse-service.shscript10.4 KB
scripts/install-aquaclaw-mirror-service.shscript5.7 KB
scripts/install-aquaclaw-runtime-heartbeat-service.shscript4.6 KB
scripts/install-openclaw-diary-cron.shscript5.9 KB
scripts/install-openclaw-heartbeat-cron.shscript5.8 KB
scripts/install-openclaw-pulse-cron.shscript3.7 KB
scripts/openclaw-cron-common.shscript6.1 KB
scripts/openclaw-cron-job-find.mjsscript1.9 KB
scripts/openclaw-diary-cron-common.shscript3.0 KB
scripts/openclaw-heartbeat-cron-common.shscript1.2 KB
scripts/path-access.mjsscript199 B
scripts/remove-aquaclaw-hosted-pulse-service.shscript1.8 KB
scripts/remove-aquaclaw-mirror-service.shscript1.8 KB
scripts/remove-aquaclaw-runtime-heartbeat-service.shscript1.8 KB
scripts/remove-openclaw-diary-cron.shscript1.0 KB
scripts/remove-openclaw-heartbeat-cron.shscript1.0 KB
scripts/remove-openclaw-pulse-cron.shscript1.0 KB
scripts/resolve-aquaclaw-paths.mjsscript4.9 KB
scripts/resolve-openclaw-delivery-target.mjsscript7.6 KB
scripts/resolve-openclaw-user-timezone.mjsscript4.0 KB
scripts/show-aquaclaw-hosted-pulse-service.shscript6.0 KB
scripts/show-aquaclaw-mirror-service.shscript4.7 KB
scripts/show-aquaclaw-runtime-heartbeat-service.shscript2.7 KB
scripts/show-openclaw-diary-cron.shscript2.2 KB
scripts/show-openclaw-heartbeat-cron.shscript1.7 KB
scripts/show-openclaw-pulse-cron.shscript1.1 KB
scripts/soul-personality.mjsscript16.4 KB
scripts/sync-aquaclaw-tools-md.mjsscript3.8 KB
scripts/sync-aquaclaw-tools-md.shscript156 B

scripts/aqua-hosted-pulse-loop.mjs

View on GitHub
#!/usr/bin/env node

import { execFile } from 'node:child_process';
import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';

import {
  DEFAULT_WORKSPACE_ROOT,
  resolveHostedConfigPath,
  resolveHostedPulseStatePath,
} from './hosted-aqua-common.mjs';

const execFileAsync = promisify(execFile);

const LABEL = 'ai.aquaclaw.hosted-pulse';
const DEFAULT_MIN_INTERVAL_SECONDS = 15 * 60;
const DEFAULT_JITTER_SECONDS = 20 * 60;
const DEFAULT_FAILURE_MIN_SECONDS = 3 * 60;
const DEFAULT_FAILURE_JITTER_SECONDS = 2 * 60;
const DEFAULT_PULSE_TIMEOUT_MS = 120_000;
const DEFAULT_FEED_LIMIT = 6;
const DEFAULT_SOCIAL_COOLDOWN_MINUTES = 150;
const DEFAULT_DM_COOLDOWN_MINUTES = 150;
const DEFAULT_DM_TARGET_COOLDOWN_MINUTES = 720;
const DEFAULT_TIME_ZONE = 'Asia/Shanghai';
const DEFAULT_QUIET_HOURS = '00:00-08:00';
const DEFAULT_LOOP_STATE_FILE_NAME = 'hosted-pulse-loop-state.json';
const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
const PULSE_SCRIPT_PATH = fileURLToPath(new URL('./aqua-hosted-pulse.mjs', import.meta.url));

function printHelp() {
  console.log(`Usage: aqua-hosted-pulse-loop.mjs [--once] [--print-paths] [--help]

Environment:
  OPENCLAW_WORKSPACE_ROOT                               OpenClaw workspace root (default: ${DEFAULT_WORKSPACE_ROOT})
  AQUACLAW_HOSTED_CONFIG                                Hosted Aqua config path override
  AQUACLAW_HOSTED_PULSE_STATE                           Hosted pulse state file override
  AQUACLAW_HOSTED_PULSE_LOOP_STATE_FILE                 Hosted pulse loop state file override
  AQUACLAW_HOSTED_PULSE_MIN_SECONDS                     Base interval seconds (default: ${DEFAULT_MIN_INTERVAL_SECONDS})
  AQUACLAW_HOSTED_PULSE_JITTER_SECONDS                  Extra random interval seconds (default: ${DEFAULT_JITTER_SECONDS})
  AQUACLAW_HOSTED_PULSE_FAILURE_MIN_SECONDS             Failure retry base seconds (default: ${DEFAULT_FAILURE_MIN_SECONDS})
  AQUACLAW_HOSTED_PULSE_FAILURE_JITTER_SECONDS          Failure retry extra random seconds (default: ${DEFAULT_FAILURE_JITTER_SECONDS})
  AQUACLAW_HOSTED_PULSE_TIMEOUT_MS                      Per-tick timeout in milliseconds (default: ${DEFAULT_PULSE_TIMEOUT_MS})
  AQUACLAW_HOSTED_PULSE_FEED_LIMIT                      Sea feed limit passed to hosted pulse (default: ${DEFAULT_FEED_LIMIT})
  AQUACLAW_HOSTED_PULSE_SOCIAL_COOLDOWN_MINUTES         Fallback public-expression cooldown (default: ${DEFAULT_SOCIAL_COOLDOWN_MINUTES})
  AQUACLAW_HOSTED_PULSE_DM_COOLDOWN_MINUTES             Fallback DM cooldown (default: ${DEFAULT_DM_COOLDOWN_MINUTES})
  AQUACLAW_HOSTED_PULSE_DM_TARGET_COOLDOWN_MINUTES      Fallback per-target DM cooldown (default: ${DEFAULT_DM_TARGET_COOLDOWN_MINUTES})
  AQUACLAW_HOSTED_PULSE_TIMEZONE                        Fallback timezone (default: ${DEFAULT_TIME_ZONE})
  AQUACLAW_HOSTED_PULSE_QUIET_HOURS                     Fallback quiet hours, empty to disable (default: ${DEFAULT_QUIET_HOURS})

Notes:
  This loop is the hosted participant scheduler. It re-samples a randomized delay after every tick.
  It triggers the existing aqua-hosted-pulse script, which remains responsible for policy, cooldown, and action execution.
  --once runs exactly one hosted pulse tick and prints the child pulse JSON output.
  --print-paths shows the currently resolved config/state paths without running a pulse.
`);
}

function parsePositiveInteger(value, label) {
  const parsed = Number.parseInt(String(value), 10);
  if (!Number.isFinite(parsed) || parsed < 1) {
    throw new Error(`${label} must be a positive integer`);
  }
  return parsed;
}

function parseNonNegativeInteger(value, label) {
  const parsed = Number.parseInt(String(value), 10);
  if (!Number.isFinite(parsed) || parsed < 0) {
    throw new Error(`${label} must be a non-negative integer`);
  }
  return parsed;
}

function trimToNull(value) {
  if (typeof value !== 'string') {
    return null;
  }
  const trimmed = value.trim();
  return trimmed ? trimmed : null;
}

export function buildDelayMs(minIntervalSeconds, jitterSeconds, randomValue = Math.random()) {
  const clampedRandom = Number.isFinite(randomValue) ? Math.min(Math.max(randomValue, 0), 0.999999) : 0;
  const jitter = jitterSeconds > 0 ? Math.floor(clampedRandom * (jitterSeconds + 1)) : 0;
  return (minIntervalSeconds + jitter) * 1_000;
}

export function resolveLoopStatePath({ pulseStateFile, loopStateFile }) {
  const explicit = trimToNull(loopStateFile);
  if (explicit) {
    return path.resolve(explicit);
  }
  return path.join(path.dirname(path.resolve(pulseStateFile)), DEFAULT_LOOP_STATE_FILE_NAME);
}

function parseOptions(argv) {
  const options = {
    configPath: trimToNull(process.env.AQUACLAW_HOSTED_CONFIG),
    failureJitterSeconds: parseNonNegativeInteger(
      process.env.AQUACLAW_HOSTED_PULSE_FAILURE_JITTER_SECONDS || DEFAULT_FAILURE_JITTER_SECONDS,
      'AQUACLAW_HOSTED_PULSE_FAILURE_JITTER_SECONDS',
    ),
    failureMinSeconds: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_FAILURE_MIN_SECONDS || DEFAULT_FAILURE_MIN_SECONDS,
      'AQUACLAW_HOSTED_PULSE_FAILURE_MIN_SECONDS',
    ),
    feedLimit: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_FEED_LIMIT || DEFAULT_FEED_LIMIT,
      'AQUACLAW_HOSTED_PULSE_FEED_LIMIT',
    ),
    jitterSeconds: parseNonNegativeInteger(
      process.env.AQUACLAW_HOSTED_PULSE_JITTER_SECONDS || DEFAULT_JITTER_SECONDS,
      'AQUACLAW_HOSTED_PULSE_JITTER_SECONDS',
    ),
    loopStateFile: trimToNull(process.env.AQUACLAW_HOSTED_PULSE_LOOP_STATE_FILE),
    minIntervalSeconds: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_MIN_SECONDS || DEFAULT_MIN_INTERVAL_SECONDS,
      'AQUACLAW_HOSTED_PULSE_MIN_SECONDS',
    ),
    once: false,
    printPaths: false,
    pulseStateFile: trimToNull(process.env.AQUACLAW_HOSTED_PULSE_STATE),
    quietHours:
      process.env.AQUACLAW_HOSTED_PULSE_QUIET_HOURS !== undefined
        ? trimToNull(process.env.AQUACLAW_HOSTED_PULSE_QUIET_HOURS)
        : DEFAULT_QUIET_HOURS,
    socialCooldownMinutes: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_SOCIAL_COOLDOWN_MINUTES || DEFAULT_SOCIAL_COOLDOWN_MINUTES,
      'AQUACLAW_HOSTED_PULSE_SOCIAL_COOLDOWN_MINUTES',
    ),
    socialDmCooldownMinutes: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_DM_COOLDOWN_MINUTES || DEFAULT_DM_COOLDOWN_MINUTES,
      'AQUACLAW_HOSTED_PULSE_DM_COOLDOWN_MINUTES',
    ),
    socialDmTargetCooldownMinutes: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_DM_TARGET_COOLDOWN_MINUTES || DEFAULT_DM_TARGET_COOLDOWN_MINUTES,
      'AQUACLAW_HOSTED_PULSE_DM_TARGET_COOLDOWN_MINUTES',
    ),
    timeZone: trimToNull(process.env.AQUACLAW_HOSTED_PULSE_TIMEZONE) || DEFAULT_TIME_ZONE,
    timeoutMs: parsePositiveInteger(
      process.env.AQUACLAW_HOSTED_PULSE_TIMEOUT_MS || DEFAULT_PULSE_TIMEOUT_MS,
      'AQUACLAW_HOSTED_PULSE_TIMEOUT_MS',
    ),
    workspaceRoot: path.resolve(trimToNull(process.env.OPENCLAW_WORKSPACE_ROOT) || DEFAULT_WORKSPACE_ROOT),
  };

  for (const arg of argv) {
    if (arg === '--help') {
      printHelp();
      process.exit(0);
    }
    if (arg === '--once') {
      options.once = true;
      continue;
    }
    if (arg === '--print-paths') {
      options.printPaths = true;
      continue;
    }
    throw new Error(`unknown option: ${arg}`);
  }

  return options;
}

function resolvePaths(options) {
  const configPath = resolveHostedConfigPath({
    workspaceRoot: options.workspaceRoot,
    configPath: options.configPath || undefined,
  });
  const pulseStateFile = resolveHostedPulseStatePath({
    workspaceRoot: options.workspaceRoot,
    stateFile: options.pulseStateFile || undefined,
  });
  const loopStateFile = resolveLoopStatePath({
    pulseStateFile,
    loopStateFile: options.loopStateFile,
  });

  return {
    configPath,
    loopStateFile,
    pulseStateFile,
    workspaceRoot: options.workspaceRoot,
  };
}

async function loadLoopState(filePath) {
  try {
    const raw = await readFile(filePath, 'utf8');
    return JSON.parse(raw);
  } catch (error) {
    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
      return null;
    }
    return null;
  }
}

async function saveLoopState(filePath, state) {
  await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
  await writeFile(filePath, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
  try {
    await chmod(filePath, 0o600);
  } catch {}
}

function log(level, message, extra = undefined) {
  const prefix = `[${new Date().toISOString()}] [${LABEL}] [${level}]`;
  if (extra === undefined) {
    console.log(`${prefix} ${message}`);
    return;
  }
  console.log(`${prefix} ${message} ${JSON.stringify(extra)}`);
}

function buildPulseArgs(options, paths) {
  const args = [
    PULSE_SCRIPT_PATH,
    '--format',
    'json',
    '--workspace-root',
    paths.workspaceRoot,
    '--config-path',
    paths.configPath,
    '--state-file',
    paths.pulseStateFile,
    '--feed-limit',
    String(options.feedLimit),
    '--social-pulse-cooldown-minutes',
    String(options.socialCooldownMinutes),
    '--social-pulse-dm-cooldown-minutes',
    String(options.socialDmCooldownMinutes),
    '--social-pulse-dm-target-cooldown-minutes',
    String(options.socialDmTargetCooldownMinutes),
    '--timezone',
    options.timeZone,
  ];

  if (options.quietHours) {
    args.push('--quiet-hours', options.quietHours);
  }

  return args;
}

function shortenText(value, maxLength = 500) {
  const text = String(value || '').trim();
  if (!text) {
    return null;
  }
  if (text.length <= maxLength) {
    return text;
  }
  return `${text.slice(0, maxLength)}...`;
}

function parsePulseOutput(stdout) {
  const trimmed = String(stdout || '').trim();
  if (!trimmed) {
    throw new Error('hosted pulse returned empty stdout');
  }
  try {
    return JSON.parse(trimmed);
  } catch {
    throw new Error('hosted pulse returned invalid JSON');
  }
}

function summarizePulse(summary) {
  return {
    authoringAgentId: summary?.socialPulse?.authoring?.agentId ?? null,
    authoringErrorCode: summary?.socialPulse?.authoring?.errorCode ?? null,
    authoringOpenClawBin: summary?.socialPulse?.authoring?.openclawBin ?? null,
    authoringStatus: summary?.socialPulse?.authoring?.status ?? null,
    generatedAt: summary?.generatedAt ?? null,
    heartbeatWritten: summary?.heartbeatWritten === true,
    hubUrl: summary?.hubUrl ?? null,
    rechargeItem:
      summary?.socialPulse?.planKind === 'recharge' ? summary?.socialPulse?.plan?.suggestedItem ?? null : null,
    rechargeVenue:
      summary?.socialPulse?.planKind === 'recharge' ? summary?.socialPulse?.plan?.venueName ?? null : null,
    runtimeStatus: summary?.runtime?.status ?? null,
    sceneGenerated: Boolean(summary?.generatedScene),
    sceneReason: summary?.sceneDecision?.reason ?? null,
    socialAction: summary?.socialPulse?.action ?? null,
    socialPlanKind: summary?.socialPulse?.planKind ?? null,
    socialReason: summary?.socialPulse?.reason ?? null,
    targetHandle:
      summary?.socialPulse?.plan?.targetGatewayHandle ??
      summary?.socialPulse?.plan?.replyToGatewayHandle ??
      null,
    warningCount: Array.isArray(summary?.warnings) ? summary.warnings.length : 0,
  };
}

function summarizeExecError(error) {
  const summary = {
    message: error instanceof Error ? error.message : String(error),
    name: error instanceof Error ? error.name : 'Error',
  };

  if (typeof error?.code === 'number') {
    summary.exitCode = error.code;
  } else if (typeof error?.code === 'string') {
    summary.code = error.code;
  }
  if (typeof error?.signal === 'string' && error.signal) {
    summary.signal = error.signal;
  }
  if (typeof error?.killed === 'boolean') {
    summary.killed = error.killed;
  }
  const stdoutPreview = shortenText(error?.stdout);
  if (stdoutPreview) {
    summary.stdout = stdoutPreview;
  }
  const stderrPreview = shortenText(error?.stderr);
  if (stderrPreview) {
    summary.stderr = stderrPreview;
  }
  return summary;
}

async function runTick(options, { passthroughOutput = false } = {}) {
  const paths = resolvePaths(options);
  const previousState = await loadLoopState(paths.loopStateFile);
  const startedAt = new Date().toISOString();

  await saveLoopState(paths.loopStateFile, {
    version: 1,
    label: LABEL,
    resolvedPaths: paths,
    status: 'running',
    lastAttemptAt: startedAt,
    lastSuccessAt: previousState?.lastSuccessAt ?? null,
    lastFailureAt: previousState?.lastFailureAt ?? null,
    lastExitCode: previousState?.lastExitCode ?? null,
    lastError: previousState?.lastError ?? null,
    lastSummary: previousState?.lastSummary ?? null,
    nextDelayMs: null,
    nextRunAt: null,
    sleepMode: null,
    updatedAt: startedAt,
  });

  try {
    const child = await execFileAsync(process.execPath, buildPulseArgs(options, paths), {
      cwd: paths.workspaceRoot,
      env: process.env,
      maxBuffer: MAX_OUTPUT_BYTES,
      timeout: options.timeoutMs,
    });
    const pulseSummary = parsePulseOutput(child.stdout);
    const completedAt = new Date().toISOString();
    const loopState = {
      version: 1,
      label: LABEL,
      resolvedPaths: paths,
      status: 'ok',
      lastAttemptAt: startedAt,
      lastSuccessAt: completedAt,
      lastFailureAt: previousState?.lastFailureAt ?? null,
      lastExitCode: 0,
      lastError: null,
      lastSummary: summarizePulse(pulseSummary),
      nextDelayMs: null,
      nextRunAt: null,
      sleepMode: null,
      updatedAt: completedAt,
    };
    await saveLoopState(paths.loopStateFile, loopState);

    if (passthroughOutput) {
      process.stdout.write(child.stdout.endsWith('\n') ? child.stdout : `${child.stdout}\n`);
    } else {
      log('info', 'hosted pulse tick completed', loopState.lastSummary);
    }
    if (child.stderr && child.stderr.trim()) {
      log('warn', 'hosted pulse tick emitted stderr', { stderr: shortenText(child.stderr) });
    }

    return {
      ok: true,
      paths,
      state: loopState,
    };
  } catch (error) {
    const completedAt = new Date().toISOString();
    const summarizedError = summarizeExecError(error);
    const loopState = {
      version: 1,
      label: LABEL,
      resolvedPaths: paths,
      status: 'error',
      lastAttemptAt: startedAt,
      lastSuccessAt: previousState?.lastSuccessAt ?? null,
      lastFailureAt: completedAt,
      lastExitCode: summarizedError.exitCode ?? null,
      lastError: summarizedError,
      lastSummary: previousState?.lastSummary ?? null,
      nextDelayMs: null,
      nextRunAt: null,
      sleepMode: null,
      updatedAt: completedAt,
    };
    await saveLoopState(paths.loopStateFile, loopState);

    if (passthroughOutput) {
      if (error?.stdout) {
        process.stdout.write(error.stdout.endsWith('\n') ? error.stdout : `${error.stdout}\n`);
      }
      if (error?.stderr) {
        process.stderr.write(error.stderr.endsWith('\n') ? error.stderr : `${error.stderr}\n`);
      }
    }

    log('error', 'hosted pulse tick failed', summarizedError);
    return {
      ok: false,
      paths,
      state: loopState,
    };
  }
}

function sleep(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

async function scheduleNextTick(options, { previousState = null, paths = null, sleepMode = 'normal' } = {}) {
  const resolvedPaths = paths || resolvePaths(options);
  const priorState = previousState || (await loadLoopState(resolvedPaths.loopStateFile));
  const delayMs =
    sleepMode === 'failure-retry'
      ? buildDelayMs(options.failureMinSeconds, options.failureJitterSeconds)
      : buildDelayMs(options.minIntervalSeconds, options.jitterSeconds);
  const nextRunAt = new Date(Date.now() + delayMs).toISOString();
  const state = {
    version: 1,
    label: LABEL,
    resolvedPaths,
    status: 'sleeping',
    lastAttemptAt: priorState?.lastAttemptAt ?? null,
    lastSuccessAt: priorState?.lastSuccessAt ?? null,
    lastFailureAt: priorState?.lastFailureAt ?? null,
    lastExitCode: priorState?.lastExitCode ?? null,
    lastError: priorState?.lastError ?? null,
    lastSummary: priorState?.lastSummary ?? null,
    nextDelayMs: delayMs,
    nextRunAt,
    sleepMode,
    updatedAt: new Date().toISOString(),
  };
  await saveLoopState(resolvedPaths.loopStateFile, state);
  log('info', 'scheduled next hosted pulse tick', {
    loopStateFile: resolvedPaths.loopStateFile,
    nextRunAt,
    seconds: Math.round(delayMs / 1_000),
    sleepMode,
  });
  await sleep(delayMs);
}

async function loop(options) {
  log('info', 'starting hosted pulse scheduler', {
    failureIntervalSeconds: {
      jitter: options.failureJitterSeconds,
      min: options.failureMinSeconds,
    },
    intervalSeconds: {
      jitter: options.jitterSeconds,
      min: options.minIntervalSeconds,
    },
    quietHours: options.quietHours,
    timeZone: options.timeZone,
    workspaceRoot: options.workspaceRoot,
  });

  await scheduleNextTick(options, { sleepMode: 'normal' });

  while (true) {
    const result = await runTick(options);
    await scheduleNextTick(options, {
      paths: result.paths,
      previousState: result.state,
      sleepMode: result.ok ? 'normal' : 'failure-retry',
    });
  }
}

async function main() {
  const options = parseOptions(process.argv.slice(2));

  if (options.printPaths) {
    console.log(JSON.stringify(resolvePaths(options), null, 2));
    return;
  }

  if (options.once) {
    const result = await runTick(options, { passthroughOutput: true });
    process.exit(result.ok ? 0 : 1);
  }

  await loop(options);
}

const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

if (isMain) {
  try {
    await main();
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    process.exit(1);
  }
}
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall