dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/autotrade/src/runner.js

@@ -12,7 +12,8 @@
 // never sleep (the source paces itself) and replies land when they land.
 //
 // Every step lands in the hash-chained run ledger (ledger.ts) with the exact inputs (the tick, the message text, the
-// raw reply, the clamp). Paper only: a strategy whose mode is not "paper" is refused before the first tick. The
+// raw reply, the clamp). Paper, or real (task-1645: the paper engine plus a trade-fire signal per fill, through the
+// real-mode hook only); any other mode is refused before the first tick. The
 // sessions' day caps and allowance guard live in SessionGate (sessions.ts); with none given, the strategy's own
 // limits apply; the gate counts real usage per wall-clock day, so a fast --replay over many tape days never resets
 // the $/day cap. The host part at the end of this file (lock, rendezvous, heartbeat) is what the CLI uses.
@@ -33,14 +34,24 @@ export function simExecutor(x) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const REVIEW = ['time_review', 'time_tighten'];
 const INFO_ONLY = ['mechanical_exit', 'stuck'];
+/** Session ends that fail the same way every time: no new session for the rest of the run. */
+const GUARD_REASONS = new Set(['account-mismatch', 'not-tool-less', 'account-unavailable']);
 async function* fromArray(ticks) { for (const k of ticks)
     yield k; }
 export async function runAutotrade(o) {
     const s = o.strategy;
     // task-1571: autotrade runs on paper only. dexterm holds no key and places no live order; live trading happens in the
     // Telegram trading bot of the user's choice.
-    if (s.mode !== 'paper')
-        throw new Error(`strategy ${s.id} is mode "${s.mode}": autotrade runs paper only (dexterm holds no key and places no live order)`);
+    // task-1645: mode "real" = the same paper engine, plus a LIVE TRADE FIRE signal per fill for the user's own executor;
+    // it needs the real-mode hook (armed on the user's terminal, checked by the host) and never runs without it.
+    if (s.mode === 'real' && !o.real)
+        throw new Error(`strategy ${s.id} is mode "real": it runs only through the real-mode host (dexterm autotrade run ${s.id} --real, once armed on your own terminal)`);
+    if (s.mode !== 'paper' && s.mode !== 'real')
+        throw new Error(`strategy ${s.id} is mode "${s.mode}": autotrade runs paper only (dexterm holds no key and places no live order); mode real runs only through the real-mode host`);
+    if (o.real && s.mode !== 'real')
+        throw new Error(`strategy ${s.id} is mode "${s.mode}": the real-mode hook is for a strategy in mode "real" only`);
+    if (o.real && (!o.executor || o.executor !== o.real))
+        throw new Error('real mode: the executor must be the real-mode signal executor itself');
     if (!o.tape && !o.source)
         throw new Error('runAutotrade needs a tape or a live source');
     const ledger = o.ledger ?? new Ledger();
@@ -86,31 +97,131 @@ export async function runAutotrade(o) {
     const pumps = new Set();
     /** Proposals waiting for an answer, by mint (task-1527). */
     const approvalsOpen = new Map();
-    ledger.add(t0, 'run_start', { strategy: s.id, version: s.version, strategyHash: s.hash, mode: s.mode, ...(s.highRisk ? { highRisk: true } : {}), tape: o.tape?.source ?? o.source.name, ticks: tapeTicks?.length ?? null, decide: decideAuto ? 'auto' : s.entry.decide, ...(o.approvals ? { approvals: o.approvals.required(s) ? 'required' : 'when-asked' } : {}), pacing: pacing.mode, executor: exec.name, caps: capsView(gate), ...(o.account ? { account: o.account.id } : {}) });
+    ledger.add(t0, 'run_start', { strategy: s.id, version: s.version, strategyHash: s.hash, mode: s.mode, ...(o.real ? { tag: 'real-signal', accountId: o.real.accountId } : {}), ...(s.highRisk ? { highRisk: true } : {}), tape: o.tape?.source ?? o.source.name, ticks: tapeTicks?.length ?? null, decide: decideAuto ? 'auto' : s.entry.decide, ...(o.approvals ? { approvals: o.approvals.required(s) ? 'required' : 'when-asked' } : {}), pacing: pacing.mode, executor: exec.name, caps: capsView(gate), ...(o.account ? { account: o.account.id } : {}) });
+    // task-1645 r2: a real run takes over the real positions an earlier run of this strategy left open (held.json),
+    // so their exits keep firing. A profile the strategy no longer has falls back to its default profile.
+    for (const p of o.real?.inherited() ?? []) {
+        const from = p.profileId;
+        if (!s.exits.profiles[p.profileId])
+            p.profileId = s.exits.default;
+        if (!book.adopt(p))
+            continue;
+        ledger.add(t0, 'position_adopted', { tag: 'real-signal', positionId: p.id, mint: p.mint, symbol: p.symbol, ...(from !== p.profileId ? { profileFrom: from } : {}), position: { ...p, fills: p.fills } });
+        say(`CARRIED ${p.symbol} (${p.mint.slice(0, 4)}…): real position from an earlier run, ${p.profileId}, cost $${(p.costUsd - p.realizedUsd).toFixed(2)} still open; its exits keep running`);
+    }
+    // 0.2.0 card B: positions a crashed run left open. A profile the (re-read) strategy no longer has falls back to
+    // its default profile, so every adopted position has exits.
+    for (const p of o.adopt ?? []) {
+        const from = p.profileId;
+        if (!s.exits.profiles[p.profileId])
+            p.profileId = s.exits.default;
+        if (!book.adopt(p))
+            continue;
+        ledger.add(t0, 'position_adopted', { positionId: p.id, mint: p.mint, symbol: p.symbol, ...(from !== p.profileId ? { profileFrom: from } : {}), position: { ...p, fills: p.fills } });
+        say(`RESUMED ${p.symbol} (${p.mint.slice(0, 4)}…): ${p.profileId}, cost $${(p.costUsd - p.realizedUsd).toFixed(2)} still open; its exits keep running`);
+    }
     const count = (rule) => { refusals[rule] = (refusals[rule] ?? 0) + 1; };
     const refuse = (rule, data) => { count(rule); ledger.add(now, 'refused', { rule, ...data }); };
     // A vet that throws or hangs is a check that could not run: the strategy's `unknown` decides (reject by default).
-    const vetCoin = async (k) => {
+    const vetCoin = async (k, ctx) => {
         let r;
         try {
-            r = await o.vet(k);
+            r = await o.vet(k, ctx);
         }
         catch (e) {
             r = { ok: false, rule: 'vet-error', detail: e.message.slice(0, 160) };
         }
         if (r.ok) {
-            vetted.add(k.mint);
+            if (!r.recheck)
+                vetted.add(k.mint);
             if (r.note)
-                ledger.add(now, 'vetted', { mint: k.mint, note: r.note.slice(0, 200) });
+                ledger.add(now, 'vetted', { mint: k.mint, note: r.note.slice(0, 200), ...(r.sizeCapPct !== undefined ? { sizeCapPct: r.sizeCapPct } : {}) });
         }
         return r;
     };
+    const vetCtx = (k, sizeUsd, h) => ({ history: h, sizeUsd, exitFloorUsd: x.minExitLiquidityUsd, maxTop10Pct: s.entry.safety.maxTop10Pct, maxDevPct: s.entry.safety.maxDevPct, unknownHolders: s.entry.safety.unknownHolders });
+    const drainGuard = s.entry.safety.rugproof?.drainGuard ?? null;
+    const stuckSince = new Map();
+    /** The liquidity read each position was bought at (the drain guard's base). */
+    const entryLiq = new Map();
+    // Paper only: a real-signal bag is still in the user's wallet, so it keeps its exit signals and carries to the next
+    // real run (validateStrategy also refuses the option outside mode paper).
+    const writeOffMin = !o.real && s.mode === 'paper' ? x.stuckWriteOffMin ?? null : null;
+    /** Positions the pool probe saw drained (no feed-priced retry while it still says so). */
+    const drained = new Set();
+    /**
+     * task-1748, every step, for every open position:
+     *  - the drain guard: an exit verdict from the pool poller (SOL vault / Jupiter, <= 10 s apart), or this coin's own
+     *    feed liquidity down more than drainGuard.liqDropPct from the entry read, sells the whole position at once. The
+     *    sale is priced on the liquidity the guard saw (0 when the route is gone), not on a lagging feed row: an
+     *    emptied pool leaves nothing to sell into, the bag goes stuck and the write-off below closes it.
+     *  - execution.stuckWriteOffMin (paper): a bag stuck that long is closed at its realizable value (sells already
+     *    made kept, the rest 0), with a written_off event and a trade_closed line, so crash recovery never adopts it.
+     */
+    const sweepOpen = async (tick) => {
+        for (const p of [...book.open.values()]) {
+            if (p.status !== 'open')
+                continue;
+            const k = latest.get(p.mint) ?? p.lastTick;
+            if (drainGuard && !p.stuck) {
+                const v = o.drain?.verdict(p.id) ?? null;
+                const base = entryLiq.has(p.id) ? entryLiq.get(p.id) ?? null : (p.liqWindow[0]?.liq || null);
+                const own = tick && tick.mint === p.mint && base && tick.liq !== null && (1 - tick.liq / base) * 100 > drainGuard.liqDropPct
+                    ? { reason: 'drain-liquidity', detail: `liquidity $${Math.round(base)} -> $${Math.round(tick.liq)} since entry (-${((1 - tick.liq / base) * 100).toFixed(1)}% > ${drainGuard.liqDropPct}%)`, liqUsd: tick.liq } : null;
+                const hit = v ?? own;
+                if (hit) {
+                    ledger.add(now, 'drain_guard', { positionId: p.id, mint: p.mint, reason: hit.reason, detail: hit.detail, liqUsd: hit.liqUsd, source: v ? 'pool-probe' : 'feed' });
+                    say(`DRAIN GUARD ${p.symbol}: ${hit.detail}`);
+                    await sellPosition(p, { ...k, t: now, liq: hit.liqUsd ?? 0 }, p.tokens, hit.reason, hit.detail);
+                    // The probe saw the pool emptied or the route gone: the lagging feed must not "sell" the bag at its old
+                    // liquidity. While the probe still says so, the monitor's stuck retry is off for this position.
+                    if (v && p.status === 'open' && p.stuck)
+                        drained.add(p.id);
+                }
+            }
+            const since = stuckSince.get(p.id);
+            if (writeOffMin !== null && p.status === 'open' && p.stuck && since !== undefined && now - since >= writeOffMin * 60e3) {
+                const ct = book.close(p, now, 'written-off', true);
+                o.drain?.unwatch(p.id);
+                stuckSince.delete(p.id);
+                ledger.add(now, 'written_off', { positionId: p.id, mint: p.mint, stuckMin: Math.round((now - since) / 6e3) / 10, realizedUsd: ct.proceedsUsd, costUsd: ct.costUsd, why: `stuck ${writeOffMin} min under the exit floor: closed at realizable value (the rest counts 0)` });
+                ledger.add(now, 'trade_closed', { trade: { ...ct, fills: undefined }, entryPrice: p.entryPrice, peakPrice: p.peakPrice, troughPrice: p.troughPrice ?? null, writtenOff: true });
+                say(`WRITTEN OFF ${p.symbol}: stuck ${writeOffMin} min, ${ct.pnlPct}% realized`);
+            }
+            if (p.status === 'closed') {
+                const c = byPosition.get(p.id);
+                if (c) {
+                    if (c.inflight)
+                        await c.inflight;
+                    await closeCandidate(c, 'position-closed');
+                }
+            }
+        }
+    };
     const liveCandidateSessions = () => [...cands.values()].filter((q) => q.session && !q.positionId).length;
     const everyLive = () => [...new Set([...cands.values(), ...byPosition.values()])];
     const newCand = (k, matched, session, kind, positionId) => ({
         mint: k.mint, symbol: k.symbol, since: now, lastMatch: now, matched, session, sessionKind: kind, lastSent: view(k), lastSentT: now, seq: 0,
         inflight: null, pendingText: [], notes: [], closing: false, positionId, awaitingReview: null, oneShot: kind === 'position', costSeen: 0, turns: 0, lastDecision: null,
     });
+    /**
+     * Why the session's process ended on its own (null while alive). A session that proved the account or its tool list
+     * wrong (or had no account) blocks new sessions for the run; the guard is logged once, by the session that set it.
+     * Checked on every path that learns of a death: a null reply AND a close (a candidate's TTL can close a session that
+     * already died, before its null reply is read; task-1712).
+     */
+    let guardLogged = false;
+    const sessionDied = (c) => {
+        const died = c.session?.endReason?.() ?? null;
+        if (c.session && died && GUARD_REASONS.has(died)) {
+            if (!guardLogged && (gate.blocked === null || gate.blockedBy === c.session.id)) {
+                guardLogged = true;
+                ledger.add(now, 'guard', { state: died, effect: 'no new sessions this run; mechanical exits continue', sessionId: c.session.id });
+            }
+            gate.block(died, c.session.id);
+        }
+        return died;
+    };
     const closeCandidate = async (c, reason) => {
         if (c.closing)
             return;
@@ -132,8 +243,11 @@ export async function runAutotrade(o) {
                 c.costSeen = st.costUsd;
             }
             sessionCost += st.costUsd;
-            ledger.add(now, 'session_end', { sessionId: c.session.id, sessionKind: c.sessionKind, mint: c.mint, reason, turns: st.turns, costUsd: st.costUsd });
-            say(`session ${c.session.id} ended (${reason}) · ${st.turns} turns · $${st.costUsd.toFixed(4)}`);
+            // A session that had already failed its proof ended for that reason, whatever closed its candidate.
+            const died = sessionDied(c);
+            const why = died && GUARD_REASONS.has(died) ? died : reason;
+            ledger.add(now, 'session_end', { sessionId: c.session.id, sessionKind: c.sessionKind, mint: c.mint, reason: why, turns: st.turns, costUsd: st.costUsd });
+            say(`session ${c.session.id} ended (${why}) · ${st.turns} turns · $${st.costUsd.toFixed(4)}`);
         }
     };
     const sellPosition = async (p, k, tokens, reason, detail) => {
@@ -143,21 +257,37 @@ export async function runAutotrade(o) {
         if ('refused' in f) {
             if (!p.stuck) {
                 p.stuck = true;
+                stuckSince.set(p.id, now);
                 ledger.add(now, 'stuck', { positionId: p.id, mint: p.mint, why: f.refused, reason });
                 say(`STUCK ${p.symbol}: cannot sell (${f.refused})`);
             }
             return;
         }
         p.stuck = false;
-        ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), detail });
+        stuckSince.delete(p.id);
+        ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), detail, ...sigTag(f) });
         say(`SELL ${p.symbol} ${reason}: $${f.usd.toFixed(2)} at ${lvl(f.price, k)} (impact ${f.impactPct}%) — ${detail}`);
         const ct = book.sell(p, f);
+        if (ct)
+            o.drain?.unwatch(p.id);
         if (ct) {
             // task-1530: the price extremes the monitor saw while held (the trade ledger's MFE / MAE)
-            ledger.add(now, 'trade_closed', { trade: { ...ct, fills: undefined }, entryPrice: p.entryPrice, peakPrice: p.peakPrice, troughPrice: p.troughPrice ?? null });
+            ledger.add(now, 'trade_closed', { trade: { ...ct, fills: undefined }, entryPrice: p.entryPrice, peakPrice: p.peakPrice, troughPrice: p.troughPrice ?? null, ...(o.real ? { tag: 'real-signal' } : {}) });
             say(`CLOSED ${ct.symbol}: ${ct.pnlUsd >= 0 ? '+' : ''}$${ct.pnlUsd.toFixed(2)} (${ct.pnlPct}%) by ${ct.exitReason}`);
         }
     };
+    /** task-1748: a young or partly verified pool takes at most the vet's sizeCapPct of the strategy's pick. */
+    const capYoungPool = (r, c) => {
+        if (!r.ok || c.sizeCapPct === undefined)
+            return r;
+        const capUsd = Math.round(r.usd * c.sizeCapPct) / 100;
+        if (capUsd >= r.usd)
+            return r;
+        if (capUsd < s.sizing.minUsd)
+            return { ok: false, refused: 'below-min-after-rugproof-young-pool', clamps: [...r.clamps, { rule: 'rugproof-young-pool', fromUsd: r.usd, toUsd: capUsd }] };
+        const f = r.usd ? capUsd / r.usd : 1;
+        return { ...r, usd: capUsd, firstTrancheUsd: Math.round(r.firstTrancheUsd * f * 100) / 100, clamps: [...r.clamps, { rule: 'rugproof-young-pool', fromUsd: r.usd, toUsd: capUsd }] };
+    };
     /** Apply a validated decision at the current virtual time. */
     const apply = async (c, d) => {
         const k = latest.get(c.mint);
@@ -182,7 +312,7 @@ export async function runAutotrade(o) {
                 return;
             }
             const req = { profile: d.profile, sizePct: d.sizePct, sizeUsd: d.sizeUsd, confidence: d.confidence };
-            const r = clampEntry(book, k, req, killed);
+            const r = capYoungPool(clampEntry(book, k, req, killed), c);
             ledger.add(now, 'clamp', { mint: c.mint, sessionId: c.session?.id ?? null, request: req, result: r.ok ? { ok: true, usd: r.usd, firstTrancheUsd: r.firstTrancheUsd, profile: r.profile.id, basis: r.basis, clamps: r.clamps } : r });
             for (const cl of r.clamps)
                 clampCount[cl.rule] = (clampCount[cl.rule] ?? 0) + 1;
@@ -325,14 +455,9 @@ export async function runAutotrade(o) {
             c.costSeen = Math.max(c.costSeen, r.costUsd);
         }
         if (!r || !r.decision.ok) {
-            const died = c.session.endReason?.() ?? null;
+            const died = sessionDied(c);
             if (!r)
                 ledger.add(now, 'session_timeout', { sessionId: c.session.id, mint: c.mint, ended: died });
-            if (died === 'account-mismatch' || died === 'not-tool-less' || died === 'account-unavailable') {
-                if (!gate.blocked)
-                    ledger.add(now, 'guard', { state: died, effect: 'no new sessions this run; mechanical exits continue', sessionId: c.session.id });
-                gate.block(died);
-            }
             if (review)
                 await noAnswer(review, !r ? (died ?? 'timeout') : 'invalid-decision');
             if (!r) {
@@ -436,16 +561,18 @@ export async function runAutotrade(o) {
                 f.reason = 'ladder-add';
                 const bookUsd = round4(book.bookEquity()); // task-1530: the book before the fill (the trade ledger's % of book)
                 book.addTranche(p, f);
-                ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), bookUsd });
+                ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), bookUsd, ...sigTag(f) });
                 say(`ADD ${k.symbol}: $${f.usd.toFixed(2)} at ${lvl(f.price, k)}`);
                 continue;
             }
             const prof = s.exits.profiles[q.profile];
             const bookUsd = round4(book.bookEquity()); // task-1530: the book before the fill (the trade ledger's % of book)
             const p = book.openPosition(k, f, prof, q.sessionId, q.trigger, q.ladder);
-            ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, profile: prof.id, ...fillMcaps(fillView(f), k), bookUsd, ...(q.ctx?.proposalId ? { proposalId: q.ctx.proposalId } : {}) });
+            ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, profile: prof.id, ...fillMcaps(fillView(f), k), bookUsd, ...(q.ctx?.proposalId ? { proposalId: q.ctx.proposalId } : {}), ...sigTag(f) });
             say(`BUY ${k.symbol} [${prof.id}]: $${f.usd.toFixed(2)} at ${lvl(f.price, k)}${f.partial ? ' (PARTIAL: impact cap)' : ''} · liq $${Math.round(k.liq ?? 0)}`);
             const c = cands.get(q.mint);
+            entryLiq.set(p.id, k.liq ?? null);
+            o.drain?.watch({ positionId: p.id, mint: p.mint, entryLiqUsd: k.liq ?? null, poolAddress: c?.pool?.address ?? null, quoteVault: c?.pool?.quoteVault ?? null, tokens: () => p.tokens });
             if (c) {
                 c.positionId = p.id;
                 byPosition.set(p.id, c);
@@ -525,18 +652,25 @@ export async function runAutotrade(o) {
             sessions: live.map((c) => ({ id: c.session.id, kind: c.sessionKind, mint: c.mint, symbol: c.symbol, turns: c.turns, costUsd: round4(c.session.costUsd()), budgetUsd: gate.caps.budgetUsdPerSession, lastDecision: c.lastDecision })),
             positions: [...book.open.values()].map((p) => {
                 const pnl = liquidationMark(p) + p.realizedUsd - p.costUsd;
-                return { mint: p.mint, symbol: p.symbol, profile: p.profileId, costUsd: round2(p.costUsd), pnlUsd: round2(pnl), pnlPct: p.costUsd ? Math.round((pnl / p.costUsd) * 1000) / 10 : 0, next: p.stuck ? 'stuck: retried every tick' : null, ...(p.costRecovered ? { freeBag: true } : {}) };
+                return { mint: p.mint, symbol: p.symbol, profile: p.profileId, costUsd: round2(p.costUsd), pnlUsd: round2(pnl), pnlPct: p.costUsd ? Math.round((pnl / p.costUsd) * 1000) / 10 : 0, next: p.stuck ? 'stuck: retried every tick' : null, ...(p.costRecovered ? { freeBag: true } : {}), ...(o.real ? { confirm: o.real.confirmOf(p.mint) ?? 'unconfirmed' } : {}) };
             }),
             ledgerTail: ledger.events.slice(-12).map((e) => ({ seq: e.seq, t: e.t, kind: e.kind, text: tailText(e) })),
             ledgerHead: ledger.head(),
             events: ledger.events.length,
+            ...(o.real ? { real: o.real.status() } : {}),
         };
     };
     const loop = tapeTicks ? fromArray(tapeTicks) : o.source.ticks;
     for await (const k of loop) {
         now = k.t;
         const v = o.safety?.() ?? null;
-        const haltWhy = v?.halt ?? (o.killSwitch?.() ? 'kill-switch' : null);
+        // task-1645: receipts land in the ledger as data; the real-mode kill switch halts like the panic file.
+        const rs = o.real?.step() ?? null;
+        for (const r of rs?.receipts ?? []) {
+            const dv = r.divergence;
+            ledger.add(now, 'receipt', { tag: 'real-signal', nonce: r.nonce, signalId: r.signalId, status: r.status, fill: r.fill, reason: r.reason, executor: r.executor, ...(dv ? { divergence: dv } : {}) });
+        }
+        const haltWhy = v?.halt ?? (o.killSwitch?.() ? 'kill-switch' : null) ?? rs?.halt ?? null;
         if (!killed && haltWhy) {
             killed = true;
             haltReason = haltWhy;
@@ -579,6 +713,7 @@ export async function runAutotrade(o) {
             ledger.add(now, 'halt', { reason: book.state.halted });
             o.approvals?.cancelAll(`halted:${book.state.halted}`);
         }
+        await sweepOpen(k);
         // Held coin → the monitor (mechanical first, then wakes).
         const pos = book.open.get(k.mint);
         const chatSell = o.approvals?.takeExit?.(k.mint) ?? null;
@@ -608,8 +743,15 @@ export async function runAutotrade(o) {
                 }
             }
         }
+        else if (pos && drained.has(pos.id) && o.drain?.verdict(pos.id)) {
+            // task-1748: still drained per the pool probe: nothing sells into an emptied pool (the write-off closes it).
+        }
         else if (pos) {
-            const prof = s.exits.profiles[pos.profileId];
+            drained.delete(pos.id);
+            const prof0 = s.exits.profiles[pos.profileId];
+            // task-1654: a real run's (or a paper scope's) maxHoldMinutes limit tightens the profile's holding cap (never loosens it).
+            const holdCap = o.real?.maxHoldMinutes?.() ?? o.maxHoldMinutes?.() ?? null;
+            const prof = holdCap !== null && (prof0.maxHoldMinutes == null || holdCap < prof0.maxHoldMinutes) ? { ...prof0, maxHoldMinutes: holdCap } : prof0;
             const acts = monitorTick(pos, prof, k, { minExitLiquidityUsd: x.minExitLiquidityUsd, sellUsd: (tok) => { const f = simSell(k, tok, x, 'estimate'); return 'refused' in f ? 0 : f.usd; } });
             const wakes = [];
             for (const a of acts) {
@@ -666,18 +808,26 @@ export async function runAutotrade(o) {
                 if (sr.pass) {
                     // Cheap pre-check so a full book does not spawn sessions it could never act on.
                     const pre = clampEntry(book, k, {}, killed);
-                    const v = pre.ok && o.vet && !vetted.has(k.mint) ? await vetCoin(k) : null;
+                    const v = pre.ok && o.vet && !vetted.has(k.mint) ? await vetCoin(k, vetCtx(k, pre.usd, h)) : null;
                     if (!pre.ok) {
                         if (!['already-open'].includes(pre.refused))
                             count(`precheck:${pre.refused}`);
                     }
                     else if (v && !v.ok) {
-                        refuse(v.rule, { mint: k.mint, symbol: k.symbol, stage: 'vet', detail: v.detail });
-                        skippedUntil.set(k.mint, Infinity);
-                        say(`SKIP ${k.symbol} (${k.mint.slice(0, 4)}…): ${v.rule} (${v.detail})`);
+                        // task-1748: a time gate (pool age, the second liquidity read) looks again later; any other refusal is for good.
+                        const retry = v.retryAfterMs !== undefined;
+                        refuse(v.rule, { mint: k.mint, symbol: k.symbol, stage: 'vet', detail: v.detail, ...(retry ? { retryAfterMs: v.retryAfterMs } : {}) });
+                        skippedUntil.set(k.mint, retry ? now + v.retryAfterMs : Infinity);
+                        say(`SKIP ${k.symbol} (${k.mint.slice(0, 4)}…): ${v.rule} (${v.detail})${retry ? `; again in ${Math.round(v.retryAfterMs / 1000)} s` : ''}`);
                     }
                     else if (decideAuto) {
                         const cand = newCand(k, sr.matched, null, 'candidate', null);
+                        if (v?.ok) {
+                            if (v.sizeCapPct !== undefined)
+                                cand.sizeCapPct = v.sizeCapPct;
+                            if (v.pool)
+                                cand.pool = v.pool;
+                        }
                         cands.set(k.mint, cand);
                         ledger.add(now, 'candidate', { mint: k.mint, symbol: k.symbol, matched: sr.matched, tick: view(k) });
                         await apply(cand, { action: 'enter', reason: 'auto' });
@@ -693,6 +843,12 @@ export async function runAutotrade(o) {
                             const session = o.sessions(sid, s, { kind: 'candidate', mint: k.mint });
                             gate.opened('candidate');
                             const cand = newCand(k, sr.matched, session, 'candidate', null);
+                            if (v?.ok) {
+                                if (v.sizeCapPct !== undefined)
+                                    cand.sizeCapPct = v.sizeCapPct;
+                                if (v.pool)
+                                    cand.pool = v.pool;
+                            }
                             cands.set(k.mint, cand);
                             ledger.add(now, 'candidate', { mint: k.mint, symbol: k.symbol, matched: sr.matched, tick: view(k) });
                             ledger.add(now, 'session_start', { sessionId: sid, sessionKind: 'candidate', agent: session.kind, mint: k.mint, model: sessionModel(session, s), budgetUsd: gate.caps.budgetUsdPerSession });
@@ -746,6 +902,14 @@ export async function runAutotrade(o) {
     while (pumps.size)
         await Promise.allSettled([...pumps]);
     const openAtEnd = [...book.open.values()].map((p) => ({ mint: p.mint, symbol: p.symbol, markUsd: round2(liquidationMark(p)), costUsd: p.costUsd, stuck: p.stuck }));
+    if (o.real) {
+        // The dead-man's graceful half: the executor hears the run is over (its outstanding nonces may be cancelled).
+        const why = killed ? `halt:${haltReason ?? 'kill'}` : o.tape ? 'end-of-tape' : 'runner-stopped';
+        // r2: what is still open is carried (held.json): the next real run of this strategy adopts it and keeps its exits.
+        o.real.carry([...book.open.values()]);
+        o.real.sendHalted(why);
+        ledger.add(now, 'real_halted', { tag: 'real-signal', reason: why, openAtEnd: openAtEnd.length });
+    }
     ledger.add(now, 'run_end', { trades: book.closed.length, openAtEnd: openAtEnd.length, cashUsd: book.state.cashUsd, markedEquityUsd: book.markedEquity(), sessionCostUsd: sessionCost, sessions: sessionsOpened, positionSessions: positionSessionsOpened, head: ledger.head() });
     publishFocus();
     if (o.onState)
@@ -772,6 +936,8 @@ export function exitPlanLine(p) {
     return `${p.id}: ${parts.join(', ')}`;
 }
 const round4 = (v) => Math.round(v * 1e4) / 1e4;
+/** task-1645: a fill that went out as a trade-fire signal: the ledger row is tagged and names the signal. */
+const sigTag = (f) => { const x = f; const g = x.signal; return g ? { tag: 'real-signal', nonce: g.nonce, signalId: g.id, ...(x.limitClamps?.length ? { limitClamps: x.limitClamps } : {}) } : {}; };
 const fillView = (f) => ({ side: f.side, usd: f.usd, tokens: Number(f.tokens.toPrecision(8)), price: f.price, avgPrice: f.avgPrice, impactPct: f.impactPct, partial: f.partial, reason: f.reason });
 /** Infinity (no runner cap) is written as null so the ledger stays JSON. */
 /** The model a session actually runs (a run's --model override wins over the strategy's), for the ledger. */

package/dist/packages/autotrade/src/service-guard.js

@@ -0,0 +1,125 @@
+// dexterm autotrade — the always-on service's guard aggregator (0.2.0 card B, AUTOTRADE-SPEC §7.3 / §7.4).
+//
+// Every 10 s (and on demand) the service folds what it can see into named guard states. Each state has ONE effect:
+//   stop            the service stops the fleet (a soft stop: no new entries, sessions closed, exits keep running)
+//   pause-entries   no new entries while it holds; lifts by itself (hysteresis where a value can flap)
+//   notice          shown in `service status` and sent once as a notification; nothing pauses
+// Open positions are never paused by any state: their exits keep running (the monitor is never paused, §7.4).
+//
+//   state id         effect          from
+//   stop-file        stop            the service STOP marker (`service stop`, a plain `touch`)
+//   panic            stop            the panic file (`dexterm wallet panic`); the fleet halts itself too
+//   disk-low         pause-entries   free space under runner.json disk.minFreeGb (default 5 GB); +1 GB to lift
+//   load-high        pause-entries   1-min load above load.pauseAboveLoad1m for load.sustainSec; lifts below resumeBelowLoad1m
+//   busy-process     pause-entries   a runner.json load.busyProcs pattern matches a running process (not ours)
+//   data-stale       pause-entries   no strategy has seen a market tick for dataStaleSec (default 300 s)
+//   runner-stale     notice          the fleet's heartbeat (runner-status.json) is older than 30 s
+//   allowance-high   notice          the model usage windows are above runner.json allowanceGuard (the fleet pauses sessions itself)
+//   day-cap          notice          the fleet's global day caps are used up (sessions resume when the day rolls)
+//   recorder-down    notice          the market recorder is installed but has written nothing for recorderStaleSec
+//                                    (default 15 min); not installed → notice with `dexterm record install`
+//   strategy-halted  notice          a strategy halted itself (daily loss / drawdown caps); one per strategy
+//
+// The guard is pure over its inputs (the service collects them); transitions come back so the caller can log one
+// ledger line and send one notification per change, never one per tick.
+export const DEFAULT_GUARD_CONFIG = {
+    minFreeGb: 5, pauseAboveLoad1m: 25, resumeBelowLoad1m: 20, sustainSec: 120, busyProcs: [],
+    dataStaleSec: 300, recorderStaleSec: 900, fiveHourMax: 0.6, sevenDayMax: 0.8,
+};
+/** runner.json → the guard's knobs (the stricter of the two never matters here: these only pause). */
+export function guardConfigFrom(rc, over = {}) {
+    return {
+        ...DEFAULT_GUARD_CONFIG,
+        ...(rc?.load ? { pauseAboveLoad1m: rc.load.pauseAboveLoad1m, resumeBelowLoad1m: rc.load.resumeBelowLoad1m, sustainSec: rc.load.sustainSec, busyProcs: [...rc.load.busyProcs] } : {}),
+        ...(rc?.disk ? { minFreeGb: rc.disk.minFreeGb } : {}),
+        ...(rc?.allowanceGuard ? { fiveHourMax: rc.allowanceGuard.fiveHourMax, sevenDayMax: rc.allowanceGuard.sevenDayMax } : {}),
+        ...over,
+    };
+}
+const gb = (n) => `${n.toFixed(1)} GB`;
+export class ServiceGuard {
+    cfg;
+    active = new Map();
+    loadAboveSince = null;
+    loadPaused = false;
+    diskLow = false;
+    constructor(cfg = DEFAULT_GUARD_CONFIG) { this.cfg = cfg; }
+    evaluate(i) {
+        const c = this.cfg;
+        const want = new Map();
+        const on = (id, effect, detail) => { want.set(id, { effect, detail }); };
+        if (i.stopFile)
+            on('stop-file', 'stop', i.stopFile);
+        if (i.panic)
+            on('panic', 'stop', `the panic switch is engaged (${i.panic}); \`dexterm wallet resume\` lifts it`);
+        if (i.freeGb !== null) {
+            if (!this.diskLow && i.freeGb < c.minFreeGb)
+                this.diskLow = true;
+            else if (this.diskLow && i.freeGb >= c.minFreeGb + 1)
+                this.diskLow = false;
+            if (this.diskLow)
+                on('disk-low', 'pause-entries', `${gb(i.freeGb)} free, under the ${gb(c.minFreeGb)} floor (runner.json disk.minFreeGb); lifts at ${gb(c.minFreeGb + 1)}`);
+        }
+        if (i.load1m !== null) {
+            if (i.load1m > c.pauseAboveLoad1m) {
+                this.loadAboveSince ??= i.now;
+                if (i.now - this.loadAboveSince >= c.sustainSec * 1000)
+                    this.loadPaused = true;
+            }
+            else {
+                this.loadAboveSince = null;
+                if (i.load1m < c.resumeBelowLoad1m)
+                    this.loadPaused = false;
+            }
+            if (this.loadPaused)
+                on('load-high', 'pause-entries', `1-min load ${i.load1m.toFixed(1)} (pauses above ${c.pauseAboveLoad1m} for ${c.sustainSec} s, resumes below ${c.resumeBelowLoad1m})`);
+        }
+        if (i.busy.length)
+            on('busy-process', 'pause-entries', `a busy process is running (${i.busy.slice(0, 3).join(', ')})`);
+        if (i.upMs >= c.dataStaleSec * 1000 && (i.dataAgeMs === null || i.dataAgeMs > c.dataStaleSec * 1000)) {
+            on('data-stale', 'pause-entries', i.dataAgeMs === null ? `no market tick since the start (${Math.round(i.upMs / 1000)} s)` : `the newest market tick is ${Math.round(i.dataAgeMs / 1000)} s old (limit ${c.dataStaleSec} s)`);
+        }
+        if (i.runnerAgeMs !== null && i.runnerAgeMs > 30_000)
+            on('runner-stale', 'notice', `the strategies' heartbeat is ${Math.round(i.runnerAgeMs / 1000)} s old`);
+        const a = i.allowance;
+        if (a && ((a.fiveHour ?? 0) > c.fiveHourMax || (a.sevenDay ?? 0) > c.sevenDayMax)) {
+            on('allowance-high', 'notice', `model usage 5 h ${pctOf(a.fiveHour)} / 7 d ${pctOf(a.sevenDay)} (limits ${pctOf(c.fiveHourMax)} / ${pctOf(c.sevenDayMax)}): no new sessions until it falls`);
+        }
+        if (i.dayCap)
+            on('day-cap', 'notice', `${i.dayCap}: no new sessions until the day rolls`);
+        if (i.recorder) {
+            if (!i.recorder.installed)
+                on('recorder-down', 'notice', 'the market recorder is not installed: backtests and tuning see no new history (`dexterm record install`)');
+            else if (i.recorder.newestAgeMs === null || i.recorder.newestAgeMs > c.recorderStaleSec * 1000)
+                on('recorder-down', 'notice', `the market recorder has written nothing for ${i.recorder.newestAgeMs === null ? 'ever' : `${Math.round(i.recorder.newestAgeMs / 60_000)} min`} (\`dexterm record status\`)`);
+        }
+        for (const [id, why] of Object.entries(i.halted))
+            on(`strategy-halted:${id}`, 'notice', `strategy ${id} halted itself (${why}); its open positions keep their exits`);
+        const transitions = [];
+        for (const [id, w] of want) {
+            const cur = this.active.get(id);
+            if (!cur) {
+                this.active.set(id, { id, effect: w.effect, detail: w.detail, since: i.now });
+                transitions.push({ id, on: true, effect: w.effect, detail: w.detail });
+            }
+            else
+                cur.detail = w.detail;
+        }
+        for (const [id, cur] of [...this.active]) {
+            if (want.has(id))
+                continue;
+            this.active.delete(id);
+            transitions.push({ id, on: false, effect: cur.effect, detail: cur.detail });
+        }
+        const states = [...this.active.values()].map((s) => ({ ...s }));
+        const stop = states.find((s) => s.effect === 'stop')?.id ?? null;
+        const pause = states.find((s) => s.effect === 'pause-entries')?.id ?? null;
+        return { states, stop, pauseEntries: pause ? `guard:${pause}` : null, transitions };
+    }
+}
+const pctOf = (v) => (v === null ? '?' : `${Math.round(v * 100)}%`);
+/** A one-line notification text for a guard transition (plain text, no paths, no secrets). */
+export function guardNoticeText(t) {
+    const what = t.effect === 'stop' ? 'STOP' : t.effect === 'pause-entries' ? 'ENTRIES PAUSED' : 'NOTICE';
+    return t.on ? `autotrade service · ${what} · ${t.id}: ${t.detail}` : `autotrade service · cleared · ${t.id}${t.effect === 'pause-entries' ? ': entries resume' : ''}`;
+}