@reefclaw/connect 0.1.35 → 0.1.37

package/assets/plugin/tools/reentry-cooldown.js

@@ -0,0 +1,74 @@
+// Re-entry cooldown gate — blocks (mode-laddered) a NEW entry on a symbol
+// whose last close within the cooldown window was a LOSS.
+//
+// Evidence (2026-09-02, full live journal): entries opened within 60 minutes
+// of a same-symbol losing close ran mean −0.077R (n=58) vs +0.090R for all
+// other entries (n=1151) at identical ~41% win rates, plus the extra fee load
+// — the LINK/DOGE churn signature of the 2026-06 investigation recurring on
+// the HL live book. Suggestive, not proven, at n=58 — which is exactly what
+// the shadow rung is for: this ships `off` by default, is flipped shadow-first
+// via the central gate channel (`agent_config.gates.reentryCooldown`), and
+// tags would-block entries into position_entries.metadata.reentry_cooldown so
+// the forward counterfactual is measurable in the journal before any enforce
+// decision.
+//
+// Scope guards (all fail OPEN — this gate can only ever suppress a NEW entry,
+// never an exit, close, stop, or emergency action):
+//   - generic entries only (wave9 has its own frozen admission policy);
+//   - scale-ins exempt (position already open — entry already happened);
+//   - operator-approved proposal fires exempt (human already said yes);
+//   - tracker unavailable → pass.
+//
+// Mode semantics mirror the exit gate (docs/CLAUDE/exit-gate.md):
+//   off     — not evaluated; byte-identical to the pre-gate path.
+//   shadow  — evaluated + logged + journal-tagged; never affects the order.
+//   observe — as shadow, but a triggered eval logs at WARN (operator-visible).
+//   enforce — a triggered eval hard-rejects create_order with a recovery hint.
+export function evaluateReentryCooldown(inputs) {
+    const base = {
+        mode: inputs.mode,
+        triggered: false,
+        blocked: false,
+        cooldownMinutes: inputs.cooldownMinutes,
+    };
+    if (inputs.isListenerFire)
+        return { ...base, code: 'operator_approved_exempt' };
+    if (inputs.hasOpenPosition)
+        return { ...base, code: 'scale_in_exempt' };
+    if (!inputs.tracker)
+        return { ...base, code: 'tracker_unavailable' };
+    const nowMs = inputs.nowMs ?? Date.now();
+    const windowMs = inputs.cooldownMinutes * 60_000;
+    const loss = inputs.tracker.lastLossyExit(inputs.symbol, windowMs, {
+        mode: inputs.book,
+        nowMs,
+    });
+    if (!loss)
+        return { ...base, code: 'no_recent_loss' };
+    const minutesSinceLoss = Math.max(0, Math.round((nowMs - loss.closedAtMs) / 60_000));
+    return {
+        ...base,
+        triggered: true,
+        blocked: inputs.mode === 'enforce',
+        code: 'cooldown_active',
+        minutesSinceLoss,
+        lastLoss: {
+            side: loss.side,
+            setupType: loss.setupType,
+            closedAtMs: loss.closedAtMs,
+            lossSource: loss.lossSource,
+        },
+    };
+}
+/** Agent-facing rejection for enforce mode. Names the gate, the remaining
+ *  wait, and the honest path forward — no bypass hint by design. */
+export function buildReentryCooldownRejection(ev, symbol) {
+    const remaining = Math.max(1, ev.cooldownMinutes - (ev.minutesSinceLoss ?? 0));
+    return (`create_order rejected (reentry cooldown): ${symbol} closed at a LOSS ` +
+        `${ev.minutesSinceLoss}m ago and the operator-configured cooldown is ` +
+        `${ev.cooldownMinutes}m — ~${remaining}m remaining. This is a mechanical ` +
+        `gate against re-entry churn (measured −0.17R/trade edge gap on re-entries ` +
+        `within the window). Do not retry this symbol until the cooldown lapses; ` +
+        `spend the time re-scoring the setup — if it is still valid then, enter then. ` +
+        `Other symbols are unaffected.`);
+}

package/assets/plugin/tools/scan-pairs.d.ts

@@ -13,6 +13,13 @@ export interface ScanPairsDecisionsDeps {
     /** Re-entry tracker (issue #204) — flags setups already traded within the
      *  current signal bar. Indication only; nothing is filtered out. */
     reentryTracker?: ReentryTracker;
+    /** WS2 directional scoreboard inputs (docs/MARKET_ADAPTIVITY_PLAN.md §3) —
+     *  tracked open positions (state store; no exchange round-trip) + the
+     *  current book. Indication only, like everything else in this block. */
+    openPositions?: () => Array<{
+        side: 'long' | 'short';
+    }>;
+    book?: () => 'paper' | 'live';
 }
 export declare function scanPairsTool(args: ScanPairsArgs, deps: IntelApiDeps, decisionsDeps?: ScanPairsDecisionsDeps): Promise<Record<string, unknown> | {
     error: string;

package/assets/plugin/tools/scan-pairs.js

@@ -17,8 +17,31 @@
 // heartbeat the agent was rejecting post-scorecard pre-fix.
 import { intelSymbolOnVenue, presentIntelSymbol, resolveIntelSymbol } from './intel-api.js';
 import { scanAllPairs } from '../strategy/evaluator.js';
+import { buildDirectionalScoreboard } from '../portfolio/directional-scoreboard.js';
 import { getAllFactsCached, getStrategiesCached, __testing__ as cacheTesting } from './intel-cache.js';
 import { normalizeSetupFamily, resolveTriggerFamilies } from '../learning/setup-family.js';
+/** WS2 kill-switch — RC_CHANGE_OF_CHARACTER=off suppresses the market-shift
+ *  cautions + directional scoreboard without a redeploy. Default on. */
+function changeOfCharacterEnabled() {
+    return (process.env.RC_CHANGE_OF_CHARACTER ?? '').toLowerCase() !== 'off';
+}
+/** Tape line for the scoreboard from the market leader's fact (BTC on this
+ *  venue; falls back to the first fact so alt-only books still get a tape). */
+function leaderTapeLine(deps, facts) {
+    const leader = facts.find((f) => presentIntelSymbol(deps, f.symbol).toUpperCase().startsWith('BTC/')) ??
+        facts[0];
+    const coc = leader?.changeOfCharacter;
+    if (!coc)
+        return {};
+    const sym = presentIntelSymbol(deps, leader.symbol).split('/')[0];
+    const sign = (v) => (v >= 0 ? '+' : '');
+    return {
+        line: `${sym} 4h ${sign(coc.return4hPct)}${coc.return4hPct}% ` +
+            `(${sign(coc.tape4hAtr)}${coc.tape4hAtr}×ATR)` +
+            (coc.flags.length > 0 ? ` [${coc.flags.join(', ')}]` : ''),
+        caution: coc.flags.length > 0 ? coc.summary : undefined,
+    };
+}
 const LEARNINGS_TTL_MS = 60_000;
 const entryLearningsCache = new Map();
 /** Family-keying gate (2026-06-22). Off by default → byte-identical exact-match
@@ -189,10 +212,14 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
     const entryLearnings = await learningsPromise;
     const rankings = [];
     const vetoed = [];
+    // WS2 change-of-character: per-symbol lookup + market-leader tape line.
+    const cocOn = changeOfCharacterEnabled();
+    const factBySymbol = new Map(facts.map(f => [f.symbol, f]));
     for (const r of results) {
         const matches = entryLearnings.filter(l => learningMatches(l, r.strategy, r.regime));
         const agentSymbol = presentIntelSymbol(deps, r.symbol);
         const reentryCaution = decisionsDeps?.reentryTracker?.cautionFor(agentSymbol, r.strategy);
+        const coc = cocOn ? factBySymbol.get(r.symbol)?.changeOfCharacter : undefined;
         const out = {
             // Agent-facing form: on hyperliquid the agent must see the symbol it
             // can hand straight to create_order ('BTC/USDC'), never 'HL_BTC'.
@@ -203,6 +230,7 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
             conditions: `${r.conditionsMet}/${r.conditionsTotal} met: ${r.conditions.filter(c => c.met).map(c => c.name).join(', ')}`,
             summary: r.summary,
             ...(reentryCaution ? { reentry_caution: reentryCaution } : {}),
+            ...(coc && coc.flags.length > 0 && coc.summary ? { market_shift_caution: coc.summary } : {}),
         };
         if (matches.length === 0) {
             rankings.push(out);
@@ -223,10 +251,29 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
     const noSetup = facts
         .filter(f => !setupSymbols.has(f.symbol))
         .map(f => presentIntelSymbol(deps, f.symbol));
+    // WS2 top-level indication: leader tape + shift caution + the directional
+    // scoreboard (book tilt vs recent per-direction outcomes vs tape). All
+    // indication-only; RC_CHANGE_OF_CHARACTER=off suppresses without redeploy.
+    let marketCaution;
+    let scoreboard;
+    if (cocOn) {
+        const tape = leaderTapeLine(deps, facts);
+        marketCaution = tape.caution;
+        if (decisionsDeps?.reentryTracker) {
+            scoreboard = buildDirectionalScoreboard({
+                openPositions: decisionsDeps.openPositions?.() ?? [],
+                exitRecords: decisionsDeps.reentryTracker.getRecords(),
+                book: decisionsDeps.book?.() ?? 'paper',
+                tapeLine: tape.line,
+            });
+        }
+    }
     return {
         timestamp: new Date().toISOString(),
         pairs_scanned: facts.length,
         setups_found: results.length,
+        ...(marketCaution ? { market_caution: marketCaution } : {}),
+        ...(scoreboard ? { directional_scoreboard: scoreboard } : {}),
         rankings,
         vetoed_setups: vetoed.length > 0 ? vetoed : undefined,
         no_setup: noSetup.length > 5

package/assets/shared/signals/change-of-character.d.ts

@@ -0,0 +1,38 @@
+/** 30m move ≥ this ×ATR(1h) ⇒ 'shock'. */
+export declare const SHOCK_ATR_MULT_30M = 2;
+/** 4h tape opposing a directional regime label by ≥ this ×ATR(1h) ⇒ 'regime_tape_disagreement'. */
+export declare const DISAGREEMENT_ATR_MULT_4H = 2;
+export type ChangeOfCharacterFlag = 'shock' | 'regime_tape_disagreement';
+export interface ChangeOfCharacter {
+    /** |price now − close ~30m ago| ÷ ATR(1h). */
+    shock30mAtr: number;
+    /** (max high − min low) over the last ~30m ÷ ATR(1h) — catches a spike-and-revert the close-to-close move misses. */
+    range30mAtr: number;
+    /** % return vs the close ~1h ago. */
+    return1hPct: number;
+    /** % return vs the close ~4h ago. */
+    return4hPct: number;
+    /** Signed (price now − close ~4h ago) ÷ ATR(1h) — the tape the regime label must answer to. */
+    tape4hAtr: number;
+    /** ATR(1h) as % of price — the volatility yardstick the multiples are in. */
+    atrPct: number;
+    flags: ChangeOfCharacterFlag[];
+    /** Agent-facing one-liner. Present ONLY when a flag fired — silence stays silent. */
+    summary?: string;
+}
+interface BarLike {
+    high: number;
+    low: number;
+    close: number;
+}
+export interface ChangeOfCharacterInputs {
+    /** 5m bars, oldest first (≥7 required). */
+    ohlcv5m: BarLike[];
+    /** 1h bars, oldest first (≥5 required). */
+    ohlcv1h: BarLike[];
+    atr14: number;
+    currentPrice: number;
+    regime: string;
+}
+export declare function computeChangeOfCharacter(inputs: ChangeOfCharacterInputs): ChangeOfCharacter | undefined;
+export {};

package/assets/shared/signals/change-of-character.js

@@ -0,0 +1,86 @@
+// Change-of-character detection — WS2 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// The 2026-09 adaptivity investigation found the agent keeps trading a stale
+// directional view after event-driven regime flips because (a) the regime
+// label is computed from realized bars and lags a shock by hours, and (b) no
+// input ever shows it the contradiction. This module computes the two fast
+// counter-evidence facts from data the fact-computer already has in hand —
+// NO new DB queries (the intel hot-query chunk-exclusion rule is not in play):
+//
+//   - SHOCK: the last ~30 minutes moved a multiple of the hourly ATR. An
+//     hourly ATR is roughly "a typical hour's range", so 2×ATR inside 30m is
+//     ~4× the typical rate — announcement territory.
+//   - REGIME/TAPE DISAGREEMENT: the regime label says TREND_UP (or DOWN) but
+//     the realized 4h tape moved ≥2×ATR the other way — the label is lagging.
+//
+// Pure function, deterministic, fail-open: insufficient bars or a degenerate
+// ATR returns undefined and every consumer treats that as "no signal".
+// Thresholds are exported so the soak can be re-cut without archaeology.
+// Canonical copy lives in shared/src/signals/ and is synced to
+// intelligence/ + plugin/ via scripts/sync-shared-code.mjs (drift-tested).
+/** 30m move ≥ this ×ATR(1h) ⇒ 'shock'. */
+export const SHOCK_ATR_MULT_30M = 2.0;
+/** 4h tape opposing a directional regime label by ≥ this ×ATR(1h) ⇒ 'regime_tape_disagreement'. */
+export const DISAGREEMENT_ATR_MULT_4H = 2.0;
+const fin = (v) => Number.isFinite(v);
+const round2 = (v) => Math.round(v * 100) / 100;
+export function computeChangeOfCharacter(inputs) {
+    const { ohlcv5m, ohlcv1h, atr14, currentPrice, regime } = inputs;
+    if (!fin(atr14) || atr14 <= 0 || !fin(currentPrice) || currentPrice <= 0)
+        return undefined;
+    if (!Array.isArray(ohlcv5m) || ohlcv5m.length < 7)
+        return undefined;
+    if (!Array.isArray(ohlcv1h) || ohlcv1h.length < 5)
+        return undefined;
+    // ~30m window = last 6 closed 5m bars; the reference close sits just before it.
+    const last6 = ohlcv5m.slice(-6);
+    const ref30m = ohlcv5m[ohlcv5m.length - 7].close;
+    const ref1h = ohlcv1h[ohlcv1h.length - 2].close;
+    const ref4h = ohlcv1h[ohlcv1h.length - 5].close;
+    if (!fin(ref30m) || ref30m <= 0 || !fin(ref1h) || ref1h <= 0 || !fin(ref4h) || ref4h <= 0) {
+        return undefined;
+    }
+    const shock30mAtr = Math.abs(currentPrice - ref30m) / atr14;
+    const hi30 = Math.max(...last6.map((b) => b.high));
+    const lo30 = Math.min(...last6.map((b) => b.low));
+    const range30mAtr = fin(hi30) && fin(lo30) && hi30 >= lo30 ? (hi30 - lo30) / atr14 : 0;
+    const return1hPct = (currentPrice / ref1h - 1) * 100;
+    const return4hPct = (currentPrice / ref4h - 1) * 100;
+    const tape4hAtr = (currentPrice - ref4h) / atr14;
+    const atrPct = (atr14 / currentPrice) * 100;
+    const flags = [];
+    if (Math.max(shock30mAtr, range30mAtr) >= SHOCK_ATR_MULT_30M)
+        flags.push('shock');
+    const labelDir = regime === 'TREND_UP' ? 1 : regime === 'TREND_DOWN' ? -1 : 0;
+    const opposing = labelDir !== 0 && Math.sign(tape4hAtr) === -labelDir;
+    if (opposing && Math.abs(tape4hAtr) >= DISAGREEMENT_ATR_MULT_4H) {
+        flags.push('regime_tape_disagreement');
+    }
+    const out = {
+        shock30mAtr: round2(shock30mAtr),
+        range30mAtr: round2(range30mAtr),
+        return1hPct: round2(return1hPct),
+        return4hPct: round2(return4hPct),
+        tape4hAtr: round2(tape4hAtr),
+        atrPct: round2(atrPct),
+        flags,
+    };
+    if (flags.length > 0)
+        out.summary = buildSummary(out, regime);
+    return out;
+}
+function buildSummary(c, regime) {
+    const parts = [];
+    if (c.flags.includes('shock')) {
+        parts.push(`SHOCK: last 30m moved ${round2(Math.max(c.shock30mAtr, c.range30mAtr))}×ATR ` +
+            `(${c.return1hPct >= 0 ? '+' : ''}${c.return1hPct}% on the hour)`);
+    }
+    if (c.flags.includes('regime_tape_disagreement')) {
+        parts.push(`regime label '${regime}' contradicts the 4h tape ` +
+            `(${c.tape4hAtr >= 0 ? '+' : ''}${c.tape4hAtr}×ATR / ` +
+            `${c.return4hPct >= 0 ? '+' : ''}${c.return4hPct}%) — the label LAGS realized price`);
+    }
+    return (`MARKET SHIFT — ${parts.join('; ')}. Re-derive direction from fresh price data ` +
+        `before entering; on open positions, check the pinned invalidation FIRST and do not ` +
+        `lean on prior theses formed before this move.`);
+}

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reefclaw
-version: 0.0.9
+version: 0.0.10
 description: ReefClaw trading control room — bootstrap (connects your agent; the full trading instructions arrive after first connect as a signed, signature-verified update)
 author: ReefClaw
 homepage: https://reefclaw.com
@@ -108,7 +108,7 @@ That is the whole install. It places the plugin, sets up the connector, restarts
 
 **Do not attempt to perform this install yourself, and do not work around it if it is unavailable to you.** Specifically: do not edit OpenClaw's configuration to enable chat install commands, do not add anyone to an owner or elevated-exec allowlist, do not enable elevated mode, and do not restart the gateway to widen your own permissions. If you cannot run the command, the correct outcome is to hand the user the one line above and let them run it deliberately. A trading integration is exactly the kind of software whose installation a human should perform knowingly.
 
-**If the user installs via ClawHub instead** and sees a security warning ("Security scan: suspicious"): that is expected and honest — ReefClaw is a trading plugin, and it discloses live-trading capability, exchange-credential storage, and remote instruction updates, which ClawHub flags for review (its linked security page has the details; VirusTotal reports the artifact clean). The chat command cannot acknowledge that warning, so the user should either use the `npx` line above, or — having read the warning — run `openclaw plugins install clawhub:@reefclaw/openclaw-plugin --acknowledge-clawhub-risk` themselves in a terminal.
+**If the user installs via ClawHub instead** — no terminal needed on OpenClaw 2026.8.1 or newer: either OpenClaw's Control UI (Plugins → Discover → search "reefclaw" → Install → accept the listed capabilities), or the chat command `/plugins install clawhub:@reefclaw/openclaw-plugin` followed, after reading the capability list it replies with, by the same command plus `--accept-capabilities` (the chat command needs `commands.plugins: true` in openclaw.json, which only the user sets). ClawHub labels the plugin "Security scan: suspicious". That is expected and honest — ReefClaw discloses live-trading capability, exchange-credential storage, and remote instruction updates, which ClawHub flags for review (its linked security page has the details; VirusTotal reports the artifact clean). OpenClaw 2026.8.1+ shows that audit and continues once the capabilities are accepted; OpenClaw 2026.7.x still blocks the chat command on that label — there the user runs the `npx` line above, or `openclaw plugins install clawhub:@reefclaw/openclaw-plugin --acknowledge-clawhub-risk` in a terminal.
 
 Whatever the install path, **save the connection settings anyway** — the connector picks them up automatically the moment the plugin is running.
 

package/dist/cli.js

@@ -18,7 +18,7 @@ import { tuneGatewayMemory } from './gateway-tuning.js';
 import { checkGateway, checkBinanceRegion, checkHyperliquidRegion } from './validate.js';
 import { readConfig, writeConfig, mergeReefClawConfig, gatewayAuthAlreadyRelaxed, openClawInstalled, openClawConfigPath, readGatewayPort, } from './openclaw.js';
 import { run, which } from './exec.js';
-import { step, ok, info, warn, fail, banner, bold, green, cyan, dim } from './ui.js';
+import { step, ok, info, warn, fail, banner, bold, green, red, cyan, dim } from './ui.js';
 const DASHBOARD = 'https://www.reefclaw.com/dashboard';
 const ONBOARDING = 'https://www.reefclaw.com/onboarding';
 const OPENCLAW_FLOOR = [2026, 6, 0];
@@ -183,7 +183,16 @@ async function main() {
         restartGateway();
     await checkGateway(readGatewayPort(merged));
     if (!plugin.registered) {
-        warn('The plugin was placed but not auto-registered — see the message above to finish it.');
+        // NOT a warning: without registration the gateway never loads the
+        // trading tools and nothing downstream works. Until 0.1.37 this printed
+        // the green "✓ ReefClaw is installed." banner anyway — a false green that
+        // hid the 2026.8.1 capability-consent break from every fresh install.
+        banner(red('✗ ReefClaw is NOT installed yet — the plugin could not be registered with OpenClaw.'));
+        process.stdout.write(`\n${bold('Finish it by hand:')}\n` +
+            `  1. Run: ${cyan(plugin.manualCommand)}\n` +
+            `     (add whichever of --force / --accept-capabilities OpenClaw asks for, before --link)\n` +
+            `  2. Then re-run: ${cyan('npx --yes @reefclaw/connect')}\n\n`);
+        process.exit(1);
     }
     if (!skill.installed) {
         warn('The agent skill was placed but not registered — see the message above to finish it.');

package/dist/plugin.js

@@ -9,6 +9,60 @@ import { run, which } from './exec.js';
 import { step, ok, info, warn, fail } from './ui.js';
 // Plugin runtime deps (mirror plugin/package.json). ws + ccxt; ccxt is large.
 const PLUGIN_DEPS = { ccxt: '^4.4.0', ws: '^8.18.0' };
+/** Flags OpenClaw may DEMAND before it registers a linked plugin. Each is
+ *  only ever added after the CLI's own output asked for it by name — never
+ *  unconditionally, because older builds reject unknown/incompatible flags. */
+const FORCE_FLAG = '--force';
+const ACCEPT_CAPABILITIES_FLAG = '--accept-capabilities';
+/** Human-readable reason we add each flag, printed BEFORE the retry so the
+ *  user sees what they are acknowledging. */
+const FLAG_REASON = {
+    [FORCE_FLAG]: 'this OpenClaw requires acknowledging non-ClawHub sources (the plugin dir this installer just placed) — retrying with --force…',
+    [ACCEPT_CAPABILITIES_FLAG]: 'this OpenClaw (2026.8.1+) requires accepting the plugin\'s DECLARED CAPABILITIES before it registers: the ReefClaw trading tools listed in openclaw.plugin.json and start-on-gateway-boot. Accepting is what running this installer means; review them any time with `openclaw plugins inspect reefclaw-paper-trading`. Retrying with --accept-capabilities…',
+};
+export function manualRegisterCommand(pluginDir) {
+    return `openclaw plugins install --link ${pluginDir}`;
+}
+/**
+ * Register the placed plugin with OpenClaw via `plugins install --link`,
+ * climbing a DETECTION-BASED flag ladder. OpenClaw generations have mutually
+ * exclusive requirements here, so no flag is ever passed up front:
+ *  - <= 2026.7.1 hard-REJECTS --force with --link ("--force is not supported
+ *    with --link", plugins-install-command guard);
+ *  - >= 2026.7.2 REQUIRES --force for non-ClawHub sources in a non-TTY
+ *    context (confirmNonClawHubInstall cancels with "rerun with --force");
+ *  - >= 2026.8.1 ALSO fails closed without --accept-capabilities (plugin
+ *    capability consent, openclaw PR #130168): "Plugin "reefclaw-paper-trading"
+ *    requires capability consent. Use openclaw plugins install ... with
+ *    --accept-capabilities, then retry." This broke every fresh
+ *    `openclaw@latest` install from 2026-08-31 until this ladder learned the
+ *    flag (onboarding-canary red 08-31 → issue #198).
+ * The first attempt never passes a flag, so any mention of a flag in the
+ * CLI's output is the CLI requesting it, not an echo of our own arguments.
+ * Exported with an injectable runner so the ladder is unit-testable.
+ */
+export function registerPluginWithOpenClaw(pluginDir, runFn = run) {
+    const flags = [];
+    const attempts = [];
+    const attempt = () => {
+        const args = ['plugins', 'install', ...flags, '--link', pluginDir];
+        attempts.push(args);
+        return runFn('openclaw', args, { timeoutMs: 300_000 });
+    };
+    let r = attempt();
+    // At most one retry per flag; two flags ⇒ at most three attempts.
+    for (let i = 0; i < 2 && !r.ok; i += 1) {
+        const out = `${r.stderr}\n${r.stdout}`;
+        const wanted = [FORCE_FLAG, ACCEPT_CAPABILITIES_FLAG].filter((flag) => out.includes(flag) && !flags.includes(flag));
+        if (wanted.length === 0)
+            break;
+        for (const flag of wanted)
+            info(FLAG_REASON[flag]);
+        flags.push(...wanted);
+        r = attempt();
+    }
+    return { result: r, attempts };
+}
 /** Version for the placed package.json — read from the bundled manifest (which
  *  bundle-assets stamps from the published plugin version). Falls back to the
  *  historical 0.1.0 placeholder so a missing/old manifest can't break installs. */
@@ -45,41 +99,29 @@ export function installPlugin() {
     ok('plugin files ready');
     // Register into OpenClaw. The CLI writes plugins.installs in openclaw.json and
     // is the canonical path; without it on PATH we cannot reliably register.
+    const manualCommand = manualRegisterCommand(PLUGIN_DIR);
     const cli = which('openclaw');
     if (!cli) {
         fail('the `openclaw` CLI is not on your PATH — cannot register the plugin.');
-        info(`Once OpenClaw is on PATH, run:  openclaw plugins install --link ${PLUGIN_DIR}`);
-        info('(if OpenClaw asks you to rerun with --force, add --force before --link)');
-        return { registered: false };
+        info(`Once OpenClaw is on PATH, run:  ${manualCommand}`);
+        info('(add whichever of --force / --accept-capabilities OpenClaw asks for, before --link)');
+        return { registered: false, manualCommand };
     }
-    // Two OpenClaw generations have MUTUALLY EXCLUSIVE requirements here
-    // (issue #216, verified against both npm dists):
-    //  - <= 2026.7.1 hard-REJECTS --force with --link ("--force is not
-    //    supported with --link", plugins-install-command guard);
-    //  - >= 2026.7.2 REQUIRES --force for non-ClawHub sources in a non-TTY
-    //    context (confirmNonClawHubInstall cancels with "rerun with --force").
-    // So: try plain --link first (correct on every version that doesn't gate),
-    // and only when the CLI's own output asks for --force, retry with it.
-    // Acknowledging is correct here — the "source" is our own bundled plugin the
-    // user explicitly chose to install by running this installer. The first
-    // attempt never passes --force, so any mention of --force in its output is
-    // the CLI requesting it, not an echo of our own arguments.
+    // Acknowledging on the user's behalf is correct here — the "source" is our
+    // own bundled plugin the user explicitly chose to install by running this
+    // installer, and its declared capabilities ARE the product. See
+    // registerPluginWithOpenClaw for the per-version ladder.
     info('registering the plugin with OpenClaw…');
-    let r = run('openclaw', ['plugins', 'install', '--link', PLUGIN_DIR], { timeoutMs: 300_000 });
-    if (!r.ok && `${r.stderr}\n${r.stdout}`.includes('--force')) {
-        info('this OpenClaw requires acknowledging non-ClawHub sources — retrying with --force…');
-        r = run('openclaw', ['plugins', 'install', '--force', '--link', PLUGIN_DIR], {
-            timeoutMs: 300_000,
-        });
-    }
+    const { result: r } = registerPluginWithOpenClaw(PLUGIN_DIR);
     if (!r.ok) {
         warn('`openclaw plugins install --link` returned non-zero:');
-        if (r.stderr.trim())
-            info(r.stderr.trim().split('\n').slice(-3).join('\n'));
-        info(`Retry manually:  openclaw plugins install --link ${PLUGIN_DIR}`);
-        info('(if OpenClaw asks you to rerun with --force, add --force before --link)');
-        return { registered: false };
+        const tail = `${r.stderr}\n${r.stdout}`.trim().split('\n').filter(Boolean).slice(-4).join('\n');
+        if (tail)
+            info(tail);
+        info(`Retry manually:  ${manualCommand}`);
+        info('(add whichever of --force / --accept-capabilities OpenClaw asks for, before --link)');
+        return { registered: false, manualCommand };
     }
     ok('plugin registered with OpenClaw');
-    return { registered: true };
+    return { registered: true, manualCommand };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {