dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/trade/copy/auto.js

@@ -0,0 +1,385 @@
+// task-1360 Tier 3 — CAPPED AUTO-MIRROR (research/wallet-intel design §6 Stage 2), the riskiest piece, built last.
+//
+// A COPY POLICY per followed wallet (per-trade cap, daily cap, max open mirrors, cooldown, size factor, auto-disarm
+// streak, time-to-live) is DEFAULT OFF. Enabling it is a physical gesture (keypress / Phantom) that also arms a
+// standing COPY MANDATE in the plan engine — the signer trust domain — drafted with exactly those caps (clamped to
+// the engine's hard ceilings), buy-only, `maxTier: 'hands-free'`. It is further gated on the engine's own "this is
+// less safe" popup (`Settings.handsFreeAllowed`, keypress-accepted, 24 h expiry): without it nothing auto-arms.
+// Each leader BUY then goes through the Tier 2 mirror checks, becomes a PROPOSED plan (by 'copy'), and is armed
+// with a `copy-auto` proof — the WEAKEST confirmation tier, so the engine sizes it at ¼ of the per-trade cap and
+// re-checks every cap, the allow-list and the panic state at arming and again on every fill. This service holds
+// no key, cannot raise a cap (its hard ceilings are below the engine's), and comes back OFF after a restart.
+//
+// Honest limits: mirror-SELL is not built (a mirror buy is closed by the user); auto-disarm therefore counts
+// consecutive refused / failed mirrors, not realised losses, until exits exist.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { systemClock } from "../../clock.js";
+import { Journal } from "../plans/journal.js";
+import { HARD, TIERS, mandateAlive } from "../plans/mandate.js";
+import { PolicyRefusal, TERMINAL } from "../plans/engine.js";
+import { PlanError } from "../plans/plan.js";
+import { MandateError } from "../plans/mandate.js";
+import { ConfirmError } from "../plans/confirm.js";
+import { buildMirror, leaderSoldSince } from "./mirror.js";
+/** Ceilings for an auto policy: stricter than the engine's (HARD), which clamp again underneath. */
+export const AUTO_HARD = Object.freeze({
+    perTradeUsd: Math.min(100, HARD.perTradeUsd),
+    dailyUsd: Math.min(500, HARD.totalUsd),
+    maxOpen: 10,
+    minCooldownMs: 10_000,
+    maxK: 2,
+    maxDisarmStreak: 10,
+    ttlMs: Math.min(24 * 3600_000, HARD.ttlMs),
+});
+export const AUTO_DEFAULTS = Object.freeze({ perTradeUsd: 20, dailyUsd: 100, maxOpen: 3, cooldownMs: 60_000, k: 1, autoDisarmStreak: 3, ttlMs: 8 * 3600_000 });
+/** The tier an auto-mirror arms at (the weakest), and so the fraction of the per-trade cap it may use. */
+export const AUTO_TIER = 'hands-free';
+export const AUTO_SIZE_FRACTION = TIERS[AUTO_TIER].perTradeMultiplier;
+export const AUTO_GESTURE = 'copy-auto';
+/** The most one auto-mirror may be: ¼ (the hands-free tier) of the mandate's per-trade cap, which the engine clamps to its total (= the daily cap). */
+export function autoSizeCap(p) { return Math.round(Math.min(p.perTradeUsd, p.dailyUsd) * AUTO_SIZE_FRACTION * 100) / 100; }
+export class CopyAutoError extends Error {
+    reason;
+    constructor(reason, message) { super(message); this.name = 'CopyAutoError'; this.reason = reason; }
+}
+export function defaultCopyJournalPath(env = process.env) {
+    const home = env.DEXTERM_HOME && env.DEXTERM_HOME.length ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+    return join(home, 'copy.journal');
+}
+function clampNum(v, dflt, min, max) {
+    const n = typeof v === 'number' ? v : Number(v);
+    if (!Number.isFinite(n) || n <= 0)
+        return dflt;
+    return Math.min(max, Math.max(min, n));
+}
+/** Validate an untrusted policy input: every cap clamped DOWN to AUTO_HARD, never coerced upward. */
+export function draftPolicy(wallet, input) {
+    const x = input ?? {};
+    const perTradeUsd = clampNum(x.perTradeUsd, AUTO_DEFAULTS.perTradeUsd, 0.01, AUTO_HARD.perTradeUsd);
+    // independent caps: a daily cap below the per-trade cap simply means fewer / smaller mirrors (the mandate clamps
+    // its per-trade down to its total on its own; auto fires at ¼ of per-trade anyway)
+    const dailyUsd = clampNum(x.dailyUsd, AUTO_DEFAULTS.dailyUsd, 0.01, AUTO_HARD.dailyUsd);
+    return Object.freeze({
+        wallet, perTradeUsd, dailyUsd,
+        maxOpen: Math.round(clampNum(x.maxOpen, AUTO_DEFAULTS.maxOpen, 1, AUTO_HARD.maxOpen)),
+        cooldownMs: clampNum(x.cooldownMs, AUTO_DEFAULTS.cooldownMs, AUTO_HARD.minCooldownMs, 24 * 3600_000),
+        k: clampNum(x.k, AUTO_DEFAULTS.k, 0.01, AUTO_HARD.maxK),
+        autoDisarmStreak: Math.round(clampNum(x.autoDisarmStreak, AUTO_DEFAULTS.autoDisarmStreak, 1, AUTO_HARD.maxDisarmStreak)),
+        ttlMs: clampNum(x.ttlMs, AUTO_DEFAULTS.ttlMs, 60_000, AUTO_HARD.ttlMs),
+        enabled: false, mandateId: null, enabledAt: null, offReason: null,
+    });
+}
+export class CopyAuto {
+    journal;
+    plans;
+    clock;
+    market;
+    leaderIntel;
+    trades;
+    isFollowed;
+    policies = new Map();
+    autoPlans = new Map();
+    lastAt = new Map();
+    streak = new Map();
+    last = new Map();
+    panicked = false;
+    queue = Promise.resolve();
+    #runners = new Map();
+    constructor(deps) {
+        this.plans = deps.plans;
+        this.clock = deps.clock ?? systemClock;
+        this.market = deps.market;
+        this.leaderIntel = deps.leaderIntel ?? (() => null);
+        this.trades = deps.trades;
+        this.isFollowed = deps.isFollowed ?? (() => true);
+        const path = deps.journalPath === undefined ? null : deps.journalPath;
+        this.journal = new Journal({ path, clock: this.clock });
+        if (path && existsSync(path))
+            this.recover();
+    }
+    /** Rebuild policies (always OFF after a restart) and the auto-plan ledger from the journal. */
+    recover() {
+        const v = this.journal.verify();
+        if (!v.ok)
+            throw new Error(`copy journal chain broken at seq ${v.atSeq}: ${v.why}`);
+        const live = new Map(); // wallet → copy mandate that was ON at the crash/quit
+        for (const e of this.journal.events) {
+            const d = (e.data ?? {});
+            if (e.type === 'copy.policy' && typeof d.wallet === 'string')
+                this.policies.set(d.wallet, { ...draftPolicy(d.wallet, d.policy), offReason: 'off after restart: re-enable with a keypress' });
+            else if (e.type === 'copy.auto.proposed' && typeof e.planId === 'string')
+                this.autoPlans.set(e.planId, { planId: e.planId, wallet: String(d.wallet), sizeUsd: Number(d.sizeUsd) || 0, at: e.ts, armed: false, judged: false });
+            else if (e.type === 'copy.auto.armed' && typeof e.planId === 'string') {
+                const r = this.autoPlans.get(e.planId);
+                if (r)
+                    r.armed = true;
+            }
+            else if (e.type === 'copy.auto.enabled' && typeof d.wallet === 'string' && typeof e.mandateId === 'string')
+                live.set(d.wallet, e.mandateId);
+            else if (e.type === 'copy.auto.disabled' && typeof d.wallet === 'string')
+                live.delete(d.wallet);
+            else if (e.type === 'copy.policy.removed' && typeof d.wallet === 'string') {
+                this.policies.delete(d.wallet);
+                live.delete(d.wallet);
+            }
+        }
+        // Auto-mirror never survives a restart: a copy mandate the plan engine recovered as armed is revoked here, so
+        // nothing can fire until a person enables it again with a keypress (and the less-safe popup is fresh).
+        for (const [wallet, mandateId] of live) {
+            try {
+                this.plans.revokeMandate(mandateId, 'copy auto off after restart');
+            }
+            catch { /* already gone */ }
+            this.journal.append('copy.auto.disabled', { mandateId, data: { wallet, reason: 'off after restart' } });
+        }
+        this.journal.append('copy.recovered', { data: { policies: this.policies.size, autoPlans: this.autoPlans.size, revoked: live.size, note: 'auto-mirror is OFF after a restart' } });
+    }
+    // ───────────── policies ─────────────
+    policy(wallet) { return this.policies.get(wallet) ?? null; }
+    list() { return [...this.policies.values()]; }
+    /** Draft (or redraft) the caps for a wallet. Refused while enabled: a different cap is disable + a new gesture. */
+    draft(wallet, input) {
+        const cur = this.policies.get(wallet);
+        if (cur?.enabled)
+            throw new CopyAutoError('enabled', 'auto-mirror is ON for this wallet; disable it before changing its caps');
+        const p = draftPolicy(wallet, input);
+        this.policies.set(wallet, p);
+        this.journal.append('copy.policy', { data: { wallet, policy: { perTradeUsd: p.perTradeUsd, dailyUsd: p.dailyUsd, maxOpen: p.maxOpen, cooldownMs: p.cooldownMs, k: p.k, autoDisarmStreak: p.autoDisarmStreak, ttlMs: p.ttlMs } } });
+        return p;
+    }
+    remove(wallet) {
+        const cur = this.policies.get(wallet);
+        if (!cur)
+            return false;
+        if (cur.enabled)
+            this.disable(wallet, 'policy removed');
+        this.policies.delete(wallet);
+        this.journal.append('copy.policy.removed', { data: { wallet } });
+        return true;
+    }
+    /**
+     * Turn auto-mirror ON for a wallet. Needs: a physical gesture (keypress / Phantom — the same rule as arming any
+     * mandate), the engine's "less safe" popup accepted (hands-free allowed), no panic, a followed wallet, a drafted
+     * policy. Drafts + arms the COPY MANDATE with the policy's caps in one gesture.
+     */
+    enable(wallet, gesture) {
+        const cur = this.policies.get(wallet);
+        if (!cur)
+            throw new CopyAutoError('no-policy', 'draft the caps first (dexterm follow auto <addr> --per-trade … or the A key)');
+        if (cur.enabled)
+            return cur;
+        if (gesture?.gesture !== 'keypress' && gesture?.gesture !== 'phantom')
+            throw new CopyAutoError('needs-keypress', 'enabling auto-mirror needs a physical keypress (or Phantom approval); voice, agents and pipes cannot');
+        if (this.panicked)
+            throw new CopyAutoError('panicked', 'panic engaged; auto-mirror stays off');
+        if (!this.isFollowed(wallet))
+            throw new CopyAutoError('not-followed', 'follow the wallet first');
+        if (!this.plans.riskStatus().active)
+            throw new CopyAutoError('gate-on', 'the keypress gate is ON: accept the "this is less safe" popup first (G on the O screen); auto-mirror fires at the hands-free tier');
+        const now = this.clock.now();
+        const m = this.plans.draftMandate({
+            totalUsd: cur.dailyUsd, perTradeUsd: cur.perTradeUsd, perCoinUsd: cur.perTradeUsd, dailyLossUsd: cur.dailyUsd,
+            maxOpenPositions: cur.maxOpen, maxArmedPlans: cur.maxOpen, actions: ['buy'], maxTier: AUTO_TIER, ttlMs: cur.ttlMs,
+        });
+        const engine = this.plans.engine;
+        this.#runners.set(wallet, engine.authorizeCopy(m.id, engine.issueMandateProof(m.id, gesture.gesture), wallet));
+        const p = Object.freeze({ ...cur, enabled: true, mandateId: m.id, enabledAt: now, offReason: null });
+        this.policies.set(wallet, p);
+        this.streak.set(wallet, 0);
+        this.journal.append('copy.auto.enabled', { mandateId: m.id, data: { wallet, by: gesture.gesture, perTradeUsd: cur.perTradeUsd, autoSizeUsd: autoSizeCap(cur), dailyUsd: cur.dailyUsd, maxOpen: cur.maxOpen, cooldownMs: cur.cooldownMs, expiresAt: m.expiresAt } });
+        return p;
+    }
+    /** Turn it OFF (always allowed, no gesture): revokes the copy mandate, which cancels its unfilled mirrors. */
+    disable(wallet, reason = 'user') {
+        const cur = this.policies.get(wallet);
+        if (!cur)
+            return null;
+        if (!cur.enabled)
+            return cur;
+        this.#runners.delete(wallet);
+        try {
+            if (cur.mandateId)
+                this.plans.revokeMandate(cur.mandateId, `copy auto off: ${reason}`);
+        }
+        catch { /* already gone */ }
+        const p = Object.freeze({ ...cur, enabled: false, mandateId: null, enabledAt: null, offReason: reason });
+        this.policies.set(wallet, p);
+        this.journal.append('copy.auto.disabled', { mandateId: cur.mandateId, data: { wallet, reason } });
+        return p;
+    }
+    /** PANIC: every policy off, every copy mandate revoked, and the plan engine's own panic (revokes ALL mandates). */
+    panic(reason = 'panic key') {
+        this.panicked = true;
+        for (const p of this.policies.values())
+            if (p.enabled)
+                this.disable(p.wallet, `panic: ${reason}`);
+        this.journal.append('copy.panic', { data: { reason } });
+        try {
+            this.plans.panic(reason);
+        }
+        catch { /* engine already panicked */ }
+    }
+    get isPanicked() { return this.panicked; }
+    // ───────────── accounting ─────────────
+    recsFor(wallet) { return [...this.autoPlans.values()].filter((r) => r.wallet === wallet); }
+    planStatus(planId) { return this.plans.engine.status(planId); }
+    spent24h(wallet, now = this.clock.now()) {
+        return this.recsFor(wallet).filter((r) => r.armed && now - r.at < 24 * 3600_000).filter((r) => { const s = this.planStatus(r.planId); return s !== null && s !== 'cancelled' && s !== 'failed'; }).reduce((s, r) => s + r.sizeUsd, 0);
+    }
+    openCount(wallet) {
+        return this.recsFor(wallet).filter((r) => r.armed).filter((r) => { const s = this.planStatus(r.planId); return s !== null && !TERMINAL.has(s) && s !== 'proposed'; }).length;
+    }
+    status(wallet) {
+        const p = this.policies.get(wallet) ?? null;
+        const now = this.clock.now();
+        const m = p?.mandateId ? this.plans.engine.mandates.get(p.mandateId)?.m ?? null : null;
+        const last = this.lastAt.get(wallet) ?? 0;
+        return {
+            policy: p, enabled: !!p?.enabled, gateActive: this.plans.riskStatus().active,
+            mandateAlive: m ? mandateAlive(m, now).ok : false,
+            spent24hUsd: this.spent24h(wallet, now), open: this.openCount(wallet),
+            cooldownLeftMs: p ? Math.max(0, p.cooldownMs - (now - last)) : 0,
+            streak: this.streak.get(wallet) ?? 0, lastOutcome: this.last.get(wallet) ?? null, panicked: this.panicked,
+        };
+    }
+    /** Plans THIS service proposed (never a voice/agent/user plan), newest first. */
+    autoPlanIds(wallet) { return [...this.autoPlans.values()].filter((r) => !wallet || r.wallet === wallet).sort((a, b) => b.at - a.at).map((r) => r.planId); }
+    // ───────────── the auto path ─────────────
+    /** A tracker alert. Serialised; never throws (every outcome is journaled and kept for status()). */
+    onAlert(alert) {
+        const run = this.queue.then(() => this.handle(alert)).catch((e) => ({ kind: 'refused', reason: 'error', message: e instanceof Error ? e.message : String(e), planId: null }));
+        this.queue = run;
+        return run;
+    }
+    settle(wallet, out) {
+        this.last.set(wallet, out);
+        if (out.kind === 'refused') {
+            const n = (this.streak.get(wallet) ?? 0) + 1;
+            this.streak.set(wallet, n);
+            const p = this.policies.get(wallet);
+            this.journal.append('copy.auto.refused', { planId: out.planId, data: { wallet, reason: out.reason, message: out.message, streak: n } });
+            if (p?.enabled && n >= p.autoDisarmStreak)
+                this.disable(wallet, `auto-disarm: ${n} consecutive refused/failed mirrors (last: ${out.reason})`);
+        }
+        else if (out.kind === 'armed')
+            this.streak.set(wallet, 0);
+        return out;
+    }
+    async handle(alert) {
+        const wallet = alert.wallet;
+        const p = this.policies.get(wallet);
+        if (!p || !p.enabled)
+            return { kind: 'ignored', why: 'auto-mirror off for this wallet' };
+        if (alert.trade.side !== 'buy')
+            return { kind: 'ignored', why: `a ${alert.trade.side} is never mirrored` };
+        const refuse = (reason, message, planId = null) => this.settle(wallet, { kind: 'refused', reason, message, planId });
+        const gate = () => {
+            if (this.panicked)
+                return refuse('panicked', 'panic engaged');
+            if (!this.isFollowed(wallet)) {
+                this.disable(wallet, 'wallet unfollowed');
+                return refuse('not-followed', 'the wallet is no longer followed');
+            }
+            if (!this.plans.riskStatus().active)
+                return refuse('gate-on', 'the keypress gate is on (the less-safe acceptance expired or was restored); auto-mirror paused');
+            const m = p.mandateId ? this.plans.engine.mandates.get(p.mandateId)?.m ?? null : null;
+            const alive = m ? mandateAlive(m, this.clock.now()) : { ok: false, reason: 'no-mandate' };
+            if (!alive.ok) {
+                this.disable(wallet, `copy mandate ${alive.reason}`);
+                return refuse(alive.reason, 'the copy mandate is no longer alive; auto-mirror off');
+            }
+            return null;
+        };
+        const g0 = gate();
+        if (g0)
+            return g0;
+        const now = this.clock.now();
+        const sinceLast = now - (this.lastAt.get(wallet) ?? -Infinity);
+        if (sinceLast < p.cooldownMs)
+            return refuse('cooldown', `cooldown: ${Math.ceil((p.cooldownMs - sinceLast) / 1000)} s left`);
+        const open = this.openCount(wallet);
+        if (open >= p.maxOpen)
+            return refuse('max-open', `${open} open mirrors (max ${p.maxOpen})`);
+        const spent = this.spent24h(wallet, now);
+        const dailyLeft = p.dailyUsd - spent;
+        if (dailyLeft < 0.01)
+            return refuse('daily-cap', `daily cap: $${spent.toFixed(2)} of $${p.dailyUsd} used in 24 h`);
+        let market = null;
+        try {
+            market = await this.market(alert.trade.mint);
+        }
+        catch {
+            market = null;
+        }
+        const g1 = gate();
+        if (g1)
+            return g1; // re-check after the await
+        const capUsd = Math.min(autoSizeCap(p), dailyLeft);
+        const r = buildMirror(alert, {
+            now: this.clock.now(), capUsd, k: p.k, market,
+            leaderSoldSince: this.trades ? leaderSoldSince(alert, this.trades(wallet)) : null,
+            leaderIntel: this.leaderIntel(alert.trade.mint, wallet),
+        });
+        if (!r.ok)
+            return this.settle(wallet, { kind: 'refused', reason: r.reason, message: r.message, planId: null, checks: r });
+        let planId = null;
+        try {
+            const runner = this.#runners.get(wallet);
+            if (!runner)
+                return refuse('no-authority', 'enable copy automation with a fresh physical gesture');
+            const authorized = runner(r.input, r.supply, alert.trade.sig.slice(0, 16));
+            const plan = authorized.plan;
+            planId = plan.id;
+            this.autoPlans.set(plan.id, { planId: plan.id, wallet, sizeUsd: plan.sizeUsd, at: this.clock.now(), armed: false, judged: false });
+            this.journal.append('copy.auto.proposed', { planId: plan.id, data: { wallet, sizeUsd: plan.sizeUsd, mint: plan.mint, ref: plan.source.ref } });
+            const g2 = gate();
+            if (g2) {
+                this.plans.cancelPlan(plan.id, 'copy auto: gate closed');
+                return g2;
+            }
+            // Only the engine-held operation for this new proposal can arm it. No proof leaves the engine.
+            authorized.arm();
+            const rec = this.autoPlans.get(plan.id);
+            rec.armed = true;
+            this.lastAt.set(wallet, this.clock.now());
+            this.journal.append('copy.auto.armed', { planId: plan.id, mandateId: p.mandateId, data: { wallet, sizeUsd: plan.sizeUsd, tier: AUTO_TIER, lagMs: r.lagMs, driftPct: r.driftPct } });
+            return this.settle(wallet, { kind: 'armed', planId: plan.id, sizeUsd: plan.sizeUsd, mandateId: p.mandateId });
+        }
+        catch (e) {
+            if (planId) {
+                try {
+                    this.plans.cancelPlan(planId, 'copy auto: arm refused');
+                }
+                catch { /* ignore */ }
+            }
+            const reason = e instanceof PolicyRefusal || e instanceof PlanError || e instanceof MandateError || e instanceof ConfirmError ? e.reason : 'error';
+            return refuse(reason, e instanceof Error ? e.message : String(e), planId);
+        }
+    }
+    /** Judge settled auto plans for the disarm streak (a FAILED mirror counts; a done one resets). Call on a timer. */
+    tick() {
+        for (const r of this.autoPlans.values()) {
+            if (r.judged || !r.armed)
+                continue;
+            const s = this.planStatus(r.planId);
+            if (s === null || !TERMINAL.has(s))
+                continue;
+            r.judged = true;
+            const p = this.policies.get(r.wallet);
+            if (s === 'failed') {
+                const n = (this.streak.get(r.wallet) ?? 0) + 1;
+                this.streak.set(r.wallet, n);
+                this.journal.append('copy.auto.judged', { planId: r.planId, data: { wallet: r.wallet, status: s, streak: n } });
+                if (p?.enabled && n >= p.autoDisarmStreak)
+                    this.disable(r.wallet, `auto-disarm: ${n} consecutive refused/failed mirrors (last: entry failed)`);
+            }
+            else if (s === 'done') {
+                this.streak.set(r.wallet, 0);
+                this.journal.append('copy.auto.judged', { planId: r.planId, data: { wallet: r.wallet, status: s, streak: 0 } });
+            }
+        }
+    }
+    verifyJournal() { return this.journal.verify(); }
+}

package/dist/packages/data/src/trade/copy/follows.js

@@ -0,0 +1,103 @@
+// task-1360 Tier 1 — the FOLLOW LIST: wallets the user chose to watch, kept in a local JSON file
+// (~/.dexterm/follows.json, mode 600). The label policy (research/wallet-intel design §4.3/§5) binds: a name is
+// user-typed only (`by: 'user'`), never inferred from X/Telegram, never shared or exported, deletable in one
+// command (`dexterm follow purge`). Names pass the prompt firewall on the way in: an instruction-like label is
+// refused, every other label is control-stripped and clipped, so a wallet name can never carry a prompt to the
+// analyst or an escape sequence to the terminal.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { systemClock } from "../../clock.js";
+import { firewallText } from "../../social/firewall.js";
+const ADDR_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+export const FOLLOW_NAME_MAX = 24;
+export const FOLLOWS_MAX = 50;
+export function defaultFollowsPath(env = process.env) {
+    const home = env.DEXTERM_HOME && env.DEXTERM_HOME.length ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+    return join(home, 'follows.json');
+}
+export function isWalletAddress(s) { return typeof s === 'string' && ADDR_RE.test(s); }
+/** Firewall + clip a user-typed wallet label. Returns null for an instruction-like or empty label. */
+export function cleanFollowName(raw) {
+    if (raw === null || raw === undefined)
+        return { name: null, refused: null };
+    const r = firewallText(String(raw), { max: FOLLOW_NAME_MAX, keepUrls: false });
+    if (r.injection)
+        return { name: null, refused: 'label reads like an instruction; not stored' };
+    const name = r.text.trim().slice(0, FOLLOW_NAME_MAX);
+    return { name: name.length ? name : null, refused: null };
+}
+export class FollowStore {
+    path;
+    clock;
+    rows = [];
+    constructor(opts = {}) {
+        this.path = opts.path ?? null;
+        this.clock = opts.clock ?? systemClock;
+        if (this.path && existsSync(this.path))
+            this.load();
+    }
+    load() {
+        try {
+            const j = JSON.parse(readFileSync(this.path, 'utf8'));
+            this.rows = (Array.isArray(j.follows) ? j.follows : []).flatMap((x) => {
+                const r = x;
+                if (!isWalletAddress(r.addr))
+                    return [];
+                return [{ addr: r.addr, name: cleanFollowName(r.name).name, since: typeof r.since === 'number' ? r.since : 0, tier: 'poll' }];
+            });
+        }
+        catch {
+            this.rows = [];
+        }
+    }
+    save() {
+        if (!this.path)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        writeFileSync(this.path, JSON.stringify({ v: 1, follows: this.rows }, null, 2) + '\n', { mode: 0o600 });
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch { /* best effort */ }
+    }
+    list() { return this.rows.map((r) => ({ ...r })); }
+    get(addr) { const r = this.rows.find((x) => x.addr === addr); return r ? { ...r } : null; }
+    has(addr) { return this.rows.some((x) => x.addr === addr); }
+    add(addr, name) {
+        if (!isWalletAddress(addr))
+            return { ok: false, reason: 'not a base58 wallet address' };
+        if (this.rows.some((x) => x.addr === addr))
+            return { ok: false, reason: 'already followed' };
+        if (this.rows.length >= FOLLOWS_MAX)
+            return { ok: false, reason: `at most ${FOLLOWS_MAX} followed wallets (the poll budget)` };
+        const n = cleanFollowName(name);
+        if (n.refused)
+            return { ok: false, reason: n.refused };
+        const follow = { addr, name: n.name, since: this.clock.now(), tier: 'poll' };
+        this.rows.push(follow);
+        this.save();
+        return { ok: true, follow: { ...follow } };
+    }
+    rename(addr, name) {
+        const r = this.rows.find((x) => x.addr === addr);
+        if (!r)
+            return { ok: false, reason: 'not followed' };
+        const n = cleanFollowName(name);
+        if (n.refused)
+            return { ok: false, reason: n.refused };
+        r.name = n.name;
+        this.save();
+        return { ok: true, follow: { ...r } };
+    }
+    remove(addr) {
+        const before = this.rows.length;
+        this.rows = this.rows.filter((x) => x.addr !== addr);
+        if (this.rows.length !== before)
+            this.save();
+        return this.rows.length !== before;
+    }
+    /** Delete every follow and label (the local-only, deletable label store the design requires). */
+    purge() { const n = this.rows.length; this.rows = []; this.save(); return n; }
+}
+export function shortAddr(a) { return a.length > 10 ? `${a.slice(0, 4)}…${a.slice(-4)}` : a; }

package/dist/packages/data/src/trade/copy/index.js

@@ -0,0 +1,9 @@
+// task-1360 — COPY TRADING (staged): wallet tracker + alerts (Tier 1), the one-key mirror PROPOSAL (Tier 2), the
+// capped auto-mirror copy mandate (Tier 3). Personal, self-directed, non-custodial; paper/devnet only; nothing
+// here signs, holds a key, or arms anything without the plan engine's own keypress gate.
+export { SOL_LEG_MIN_LAMPORTS, tokenDeltasForOwner, lamportsDeltaFor, decodeTx, decodeWalletTrades } from "./trades.js";
+export { WIN_RATE_MIN_N, positionsOf, earlyEntryScore, walletStats } from "./stats.js";
+export { FOLLOW_NAME_MAX, FOLLOWS_MAX, defaultFollowsPath, isWalletAddress, cleanFollowName, FollowStore, shortAddr } from "./follows.js";
+export { WalletTracker, TRACKER_DEFAULTS } from "./tracker.js";
+export { MIRROR_LIMITS, leaderFillPriceUsd, buildMirror, leaderSoldSince } from "./mirror.js";
+export { AUTO_HARD, AUTO_DEFAULTS, AUTO_TIER, AUTO_SIZE_FRACTION, AUTO_GESTURE, autoSizeCap, CopyAutoError, defaultCopyJournalPath, draftPolicy, CopyAuto } from "./auto.js";

package/dist/packages/data/src/trade/copy/mirror.js

@@ -0,0 +1,91 @@
+// task-1360 Tier 2 — the one-key MIRROR TICKET (research/wallet-intel design §6 Stage 1). A followed wallet's
+// BUY alert becomes a PROPOSED order plan sized by the user's own cap, never larger than k × the leader's size
+// and never more than 1 % of the pool. The three numbers the user must see are computed here and refused on:
+// LAG (now − the leader's block) > 30 s, DRIFT (price now vs the leader's fill) > +5 %, liquidity < $25k, token
+// age < 60 s, the leader sold since, the leader is in the token's dev cluster or holds > 5 % (they are
+// distributing to you). Unknown facts are shown as unknown, never guessed. The output is a PlanInput: an inert
+// proposal for the plan engine, armed only through its own keypress / Phantom gate. Nothing here trades.
+export const MIRROR_LIMITS = Object.freeze({
+    maxLagMs: 30_000,
+    maxDriftPct: 5,
+    minLiqUsd: 25_000,
+    minAgeMs: 60_000,
+    maxLeaderHoldPct: 5,
+    /** a mirror never takes more than this fraction of the pool's liquidity */
+    maxLiqFraction: 0.01,
+    /** a mirror proposal is time-sensitive: it expires fast (plan TTL) */
+    ttlMs: 10 * 60_000,
+    slippageBps: 300,
+    maxPriceImpactPct: 3,
+});
+const pct = (n) => `${n >= 0 ? '+' : ''}${n.toFixed(1)}%`;
+const usd = (n) => (n >= 1000 ? `$${(n / 1000).toFixed(1)}k` : `$${n.toFixed(2)}`);
+/** The leader's fill price in USD per whole token, from the alerted trade (null without decimals / USD). */
+export function leaderFillPriceUsd(alert, decimals) {
+    const tr = alert.trade;
+    if (tr.usd === null || decimals === null)
+        return null;
+    const raw = Math.abs(Number(tr.tokenDelta));
+    if (!(raw > 0))
+        return null;
+    return tr.usd / (raw / 10 ** decimals);
+}
+/** Build the mirror proposal (or the refusal with every check listed). Pure. */
+export function buildMirror(alert, ctx) {
+    const checks = [];
+    const tr = alert.trade;
+    const refuse = (reason, message) => ({ ok: false, reason, message, checks });
+    if (tr.side !== 'buy')
+        return refuse('not-a-buy', `only a leader BUY can be mirrored (this is a ${tr.side})`);
+    if (tr.usd === null)
+        return refuse('unpriced', 'the leader\'s fill has no USD value (token-swap leg or no SOL price); nothing to size from');
+    const m = ctx.market;
+    if (!m || m.priceUsd === null || !(m.priceUsd > 0))
+        return refuse('no-market', 'no price for this token yet (open it, or wait for the board)');
+    // lag
+    const lagMs = tr.tKnown ? Math.max(0, ctx.now - tr.t) : null;
+    checks.push({ name: 'lag', ok: lagMs === null ? null : lagMs <= MIRROR_LIMITS.maxLagMs, detail: lagMs === null ? 'block time unknown' : `${(lagMs / 1000).toFixed(0)} s since the leader\'s block (max ${MIRROR_LIMITS.maxLagMs / 1000} s)` });
+    // drift
+    const leaderPrice = leaderFillPriceUsd(alert, m.decimals);
+    const driftPct = leaderPrice === null ? null : ((m.priceUsd - leaderPrice) / leaderPrice) * 100;
+    const priceAge = m.priceAt === null ? null : Math.max(0, ctx.now - m.priceAt);
+    checks.push({ name: 'drift', ok: driftPct === null ? null : driftPct <= MIRROR_LIMITS.maxDriftPct, detail: driftPct === null ? (m.decimals === null ? 'token decimals unknown' : 'leader fill price unknown') : `${pct(driftPct)} vs the leader\'s fill $${leaderPrice.toPrecision(3)} (now $${m.priceUsd.toPrecision(3)}${priceAge !== null ? `, ${Math.round(priceAge / 1000)} s old` : ''}; max +${MIRROR_LIMITS.maxDriftPct}%)` });
+    // liquidity
+    checks.push({ name: 'liquidity', ok: m.liqUsd === null ? null : m.liqUsd >= MIRROR_LIMITS.minLiqUsd, detail: m.liqUsd === null ? 'liquidity unknown' : `${usd(m.liqUsd)} (min ${usd(MIRROR_LIMITS.minLiqUsd)})` });
+    // age
+    checks.push({ name: 'age', ok: m.ageMs === null ? null : m.ageMs >= MIRROR_LIMITS.minAgeMs, detail: m.ageMs === null ? 'pair age unknown' : `${Math.round(m.ageMs / 1000)} s old (min ${MIRROR_LIMITS.minAgeMs / 1000} s)` });
+    // leader sold since
+    checks.push({ name: 'leader-sold', ok: ctx.leaderSoldSince === null ? null : !ctx.leaderSoldSince, detail: ctx.leaderSoldSince === null ? 'unknown' : ctx.leaderSoldSince ? 'the leader already SOLD this mint since the buy' : 'the leader still holds (as far as fetched history shows)' });
+    // leader intel
+    const li = ctx.leaderIntel;
+    checks.push({ name: 'leader-dev', ok: li === null ? null : !li.inDevCluster, detail: li === null ? 'token not scanned (M on the token)' : li.inDevCluster ? 'the leader is linked to the dev cluster: they may be distributing to you' : 'not in the dev cluster' });
+    checks.push({ name: 'leader-holds', ok: li === null || li.holdsPct === null ? null : li.holdsPct <= MIRROR_LIMITS.maxLeaderHoldPct, detail: li === null || li.holdsPct === null ? 'leader\'s share unknown' : `${li.holdsPct.toFixed(1)}% of supply (max ${MIRROR_LIMITS.maxLeaderHoldPct}%)` });
+    for (const c of checks) {
+        if (c.ok === false) {
+            const reason = c.name;
+            return refuse(reason, `refused: ${c.name} — ${c.detail}`);
+        }
+    }
+    if (m.decimals === null)
+        return refuse('no-decimals', 'token decimals unknown: open the token so its decimals and price are known, then mirror again');
+    // size = min(own cap, k × leader size, 1 % of liquidity)
+    const k = ctx.k && ctx.k > 0 ? ctx.k : 1;
+    const parts = [[ctx.capUsd, 'your cap'], [k * tr.usd, `${k}× the leader\'s ${usd(tr.usd)}`]];
+    if (m.liqUsd !== null)
+        parts.push([m.liqUsd * MIRROR_LIMITS.maxLiqFraction, '1% of liquidity']);
+    parts.sort((a, b) => a[0] - b[0]);
+    const sizeUsd = Math.floor(parts[0][0] * 100) / 100;
+    if (!(sizeUsd >= 0.01))
+        return refuse('cap', 'the mirror size rounds to nothing (raise your cap or wait for a bigger leader buy)');
+    const supply = m.mcapUsd !== null && m.mcapUsd > 0 ? m.mcapUsd / m.priceUsd : 1e9;
+    const input = {
+        mint: tr.mint, symbol: m.symbol ?? tr.mint.slice(0, 4), decimals: m.decimals, side: 'buy', sizeUsd,
+        entry: { kind: 'immediate' }, exits: [], stop: null,
+        slippageBps: MIRROR_LIMITS.slippageBps, maxPriceImpactPct: MIRROR_LIMITS.maxPriceImpactPct, ttlMs: MIRROR_LIMITS.ttlMs,
+    };
+    return { ok: true, sizeUsd, sizeWhy: `min(${parts.map((p) => `${p[1]} ${usd(p[0])}`).join(', ')})`, lagMs, driftPct, leaderPriceUsd: leaderPrice, checks, input, supply, ref: `mirror:${alert.wallet}:${tr.sig.slice(0, 16)}` };
+}
+/** Did the leader sell `mint` after the alerted buy, as far as the tracker's trades show? */
+export function leaderSoldSince(alert, trades) {
+    return trades.some((t) => t.mint === alert.trade.mint && t.side === 'sell' && (t.slot > alert.trade.slot || (t.slot === alert.trade.slot && t.sig > alert.trade.sig)));
+}