dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/cli/src/autotrade-cmd/forward.js

@@ -0,0 +1,283 @@
+// `dexterm autotrade forward start|status|stop|report` (0.2.0 card C). PAPER ONLY.
+//
+// A forward test is one strategy, frozen at its current version, on the LIVE tape, on paper, with its own bankroll and
+// run file, for a window of hours or N closed trades (whichever comes first). `start` freezes it and starts its host
+// detached (`forward run <fid>`, output in autotrade/forward/tests/<fid>.log); `--foreground` runs it in this terminal.
+// It does not take the machine's run lock, so it runs next to the always-on service. At the end of the window the
+// host flattens and writes the report: the forward numbers next to the backtest (held-out split) of the same rules.
+// `--replay TAPE` is a smoke run on a recorded tape: labelled, never counted as the forward-tested rung.
+//
+// The analyst starts and stops the same tests (strategy_forward_start / _stop, never with a bankroll of its choosing);
+// the Q screen's journey view shows them. Nothing here holds a key, signs or touches a wallet.
+import { spawn } from 'node:child_process';
+import { closeSync, openSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dextermHome, loadConfig } from '../../../custom/src/index.js';
+import { pickBasis } from '../../../data/src/basis.js';
+import { KillSwitch, createDataLayer, defaultDbPath, resolveRpcUrl } from '../../../data/src/index.js';
+import { LiveSource, SessionGate, builtinTapePath, claudeSessionFactory, createForwardTest, effectiveCaps, findForwardTest, forwardLogPath, forwardReport, hostForward, liveState, listForwardTests, loadForwardTest, loadRunnerConfig, loadTape, markLost, prepareAccount, renderDossierRecord, requestForwardStop, runnerSystemPrompt, saveForwardTest, stubSession, validateStrategy, windowText, } from '../../../autotrade/src/index.js';
+import { ollamaSessionFactory } from '../../../autotrade/src/ollama-sessions.js';
+import { parseArgs, storeFor } from "./strategies.js";
+import { larpVet, localEngine } from "./run.js";
+const BOOL = ['json', 'stub', 'foreground', 'yes'];
+export const FORWARD_USAGE = [
+    'dexterm autotrade forward start <id> [--hours H] [--trades N] [--bankroll-usd N] [--foreground] [--stub] [--engine claude|ollama] [--model M] [--replay TAPE [--ms-per-tick N]]',
+    'dexterm autotrade forward status [<id|fid>] [--json]',
+    'dexterm autotrade forward stop <id|fid>',
+    'dexterm autotrade forward report <id|fid> [--json]',
+];
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, s) => { io.stderr.write(`dexterm autotrade forward: ${s}\n`); };
+const num = (v) => (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v)) ? Number(v) : null);
+/** The dexterm entry point a detached host runs (this package's bin). */
+export const DEXTERM_BIN = fileURLToPath(new URL('../../bin/dexterm.mjs', import.meta.url));
+/** Start the host of a `starting` test detached; its output goes to the test's log file. Returns the pid. */
+export function spawnForwardHost(home, t, env, extra = [], bin = DEXTERM_BIN) {
+    const fd = openSync(forwardLogPath(home, t.forwardId), 'a', 0o600);
+    try {
+        const child = spawn(process.execPath, [bin, 'autotrade', 'forward', 'run', t.forwardId, ...extra], { detached: true, stdio: ['ignore', fd, fd], env: { ...env, DEXTERM_HOME: home } });
+        child.unref();
+        return child.pid ?? null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export async function forwardCmd(argv, io, deps = {}) {
+    const [sub, ...rest] = argv;
+    const home = dextermHome(io.env);
+    const now = deps.now ?? Date.now;
+    switch (sub) {
+        case 'start': return startCmd(rest, io, home, deps, now);
+        case 'run': return runHostCmd(rest, io, home, deps);
+        case 'status':
+        case undefined: return statusCmd(rest, io, home, now);
+        case 'stop': {
+            const ref = rest.find((a) => !a.startsWith('--'));
+            if (!ref) {
+                err(io, 'usage: dexterm autotrade forward stop <id|fid>');
+                return 2;
+            }
+            const t = findForwardTest(home, ref, now());
+            if (!t) {
+                err(io, `no forward test for ${JSON.stringify(ref)}`);
+                return 1;
+            }
+            const r = requestForwardStop(home, t.forwardId, 'cli', now());
+            if (!r.ok) {
+                err(io, r.why);
+                return 1;
+            }
+            out(io, `${r.already ? 'already asked to stop' : 'stop requested'}: ${t.forwardId} (${t.strategyId}) flattens at its next tick, writes its report and ends. A test stopped early is shown, not counted. Report: dexterm autotrade forward report ${t.forwardId}`);
+            return 0;
+        }
+        case 'report': return reportCmd(rest, io, home, now);
+        case 'help':
+        case '--help':
+        case '-h':
+            out(io, FORWARD_USAGE.join('\n'));
+            return 0;
+        default:
+            err(io, `unknown subcommand ${JSON.stringify(sub)}\n${FORWARD_USAGE.join('\n')}`);
+            return 2;
+    }
+}
+async function startCmd(argv, io, home, deps, now) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const id = pos[0];
+    if (!id) {
+        err(io, `usage: ${FORWARD_USAGE[0]}`);
+        return 2;
+    }
+    if (opts.real || opts.live) {
+        err(io, 'a forward test is paper only (a real strategy forward-tests as its paper twin)');
+        return 2;
+    }
+    const store = storeFor(io);
+    const got = store.get(id);
+    if (!got) {
+        err(io, `no strategy ${JSON.stringify(id)} (dexterm autotrade list)`);
+        return 1;
+    }
+    if (!got.ok) {
+        err(io, `${id} does not validate: ${got.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}`);
+        return 1;
+    }
+    const raw = store.raw(id);
+    const replay = typeof opts.replay === 'string' ? opts.replay : null;
+    const hours = num(opts.hours);
+    const trades = num(opts.trades);
+    if (opts.hours !== undefined && hours === null) {
+        err(io, '--hours needs a number');
+        return 2;
+    }
+    if (opts.trades !== undefined && trades === null) {
+        err(io, '--trades needs a whole number');
+        return 2;
+    }
+    const c = createForwardTest(home, got.strategy, raw, {
+        hours: hours ?? (trades === null ? 24 : null), trades, bankrollUsd: num(opts['bankroll-usd']), by: 'user', now: now(),
+        source: replay ? `replay ${replay}` : 'live', stub: !!opts.stub, msPerTick: num(opts['ms-per-tick']),
+    });
+    if (!c.ok) {
+        err(io, c.why);
+        return 1;
+    }
+    const t = c.test;
+    out(io, `forward test ${t.forwardId} · ${id} v${t.version} · PAPER · ${replay ? `replay ${replay} (a smoke run: it does not count as a forward test)` : 'live keyless data'} · own bankroll $${t.bankrollUsd} · window ${windowText(t.window)}`);
+    const extra = [...(opts.stub ? ['--stub'] : []), ...(typeof opts.engine === 'string' ? ['--engine', opts.engine] : []), ...(typeof opts.model === 'string' ? ['--model', opts.model] : [])];
+    if (opts.foreground)
+        return runHostCmd([t.forwardId, ...extra], io, home, deps);
+    const pid = (deps.spawnHost ?? ((h, x, e) => spawnForwardHost(h, x, io.env, e)))(home, t, extra);
+    // The host writes its own pid when it starts; only a test it has not picked up yet gets the spawn pid (liveness).
+    const cur = loadForwardTest(home, t.forwardId);
+    if (pid && cur && cur.state === 'starting' && cur.pid === null)
+        saveForwardTest(home, { ...cur, pid });
+    out(io, `started in the background${pid ? ` (pid ${pid})` : ''} · log ${forwardLogPath(home, t.forwardId)}`);
+    out(io, `  status: dexterm autotrade forward status ${id} · stop: dexterm autotrade forward stop ${id} · report: dexterm autotrade forward report ${id}`);
+    return 0;
+}
+/** The host (`forward run <fid>`): the live data layer (or a replay), sessions, the panic file; then hostForward. */
+async function runHostCmd(argv, io, home, deps) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const fid = pos[0];
+    const t = fid ? loadForwardTest(home, fid) : null;
+    if (!t) {
+        err(io, `no forward test ${JSON.stringify(fid ?? '')}`);
+        return 1;
+    }
+    if (t.state !== 'starting') {
+        err(io, `${t.forwardId} is ${t.state}; a forward test runs once (start a new one)`);
+        return 1;
+    }
+    const fail = (why) => { saveForwardTest(home, { ...t, state: 'failed', endedAt: Date.now(), endReason: why }); err(io, why); return 1; };
+    const kill = deps.killSwitch ?? new KillSwitch();
+    const panic = kill.engaged();
+    if (panic)
+        return fail(`the panic switch is engaged (${panic.reason}); nothing starts until \`dexterm wallet resume\``);
+    const v = validateStrategy(t.doc);
+    if (!v.ok)
+        return fail('the frozen strategy does not validate');
+    const strategy = v.strategy;
+    const cfg = loadRunnerConfig(home);
+    if (!cfg.ok)
+        return fail(`${cfg.path} is invalid: ${cfg.errors.join('; ')}`);
+    const basis = pickBasis(loadConfig(home).config.display?.priceMode, io.env);
+    const replay = t.source.startsWith('replay ') ? t.source.slice('replay '.length) : null;
+    const stub = t.stub || !!opts.stub;
+    const gate = new SessionGate(effectiveCaps(strategy, cfg.config), cfg.config.allowanceGuard);
+    const say = (s) => out(io, s);
+    let sessions;
+    if (stub)
+        sessions = stubSession();
+    else {
+        const eng = await localEngine(opts, io);
+        if ('error' in eng)
+            return fail(eng.error);
+        sessions = eng.engine === 'ollama'
+            ? ollamaSessionFactory({ client: eng.client, model: eng.model, numCtx: eng.numCtx, restriction: eng.level, live: false, systemPrompt: (s) => runnerSystemPrompt(s, { live: !replay, basis }), gate, log: () => { } })
+            : claudeSessionFactory({ bin: io.env.DEXTERM_CLAUDE_BIN || 'claude', account: () => prepareAccount(cfg.config.account, io.env), model: typeof opts.model === 'string' ? opts.model : undefined, systemPrompt: (s) => runnerSystemPrompt(s, { live: !replay, basis }), gate, log: () => { } });
+    }
+    if (replay) {
+        let tape;
+        try {
+            tape = loadTape(builtinTapePath(replay));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+        const r = await hostForward({ home, forwardId: t.forwardId, tape, sessions, gate, pacing: { mode: 'paced', msPerTick: t.msPerTick ?? 200 }, killSwitch: kill, onLine: say });
+        if (!r.ok) {
+            err(io, r.why);
+            return 1;
+        }
+        for (const l of forwardReport(home, r.test).lines)
+            say(l);
+        return 0;
+    }
+    const rpc = resolveRpcUrl({ env: io.env });
+    const data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env), rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
+    const live = new LiveSource({ store: data.store, dexscreener: data.dexscreener }, { onLog: () => { } });
+    const { McpTools } = await import('../../../mcp/src/index.js');
+    const mcp = new McpTools(data, () => ({ screen: 'autotrade-forward', actions: { mints: [], feeds: [], sortKeys: [] } }));
+    const dossier = async (k, h, matched, b) => {
+        let rec;
+        try {
+            rec = await mcp.call('get_dossier', { mint: k.mint, interval: '5m' });
+        }
+        catch (e) {
+            rec = { availability: { present: [], missing: [`dossier: ${e.message}`], knownUnavailable: [] } };
+        }
+        return renderDossierRecord(rec, { mint: k.mint, symbol: k.symbol, matched }, k, h, b, basis);
+    };
+    const larp = strategy.entry.safety.larp;
+    const vet = larp ? larpVet(larp, (mint) => mcp.call('larp_check', { mint })) : undefined;
+    const onSig = () => { requestForwardStop(home, t.forwardId, 'signal'); };
+    process.once('SIGINT', onSig);
+    process.once('SIGTERM', onSig);
+    try {
+        const r = await hostForward({
+            home, forwardId: t.forwardId, source: { name: 'live keyless data layer', ticks: live.ticks(), startT: Date.now(), stop: () => live.stop() },
+            sessions, gate, dossier, vet, pacing: { mode: 'live' }, killSwitch: kill, onLine: say,
+        });
+        if (!r.ok) {
+            err(io, r.why);
+            return 1;
+        }
+        for (const l of forwardReport(home, r.test).lines)
+            say(l);
+        return r.test.state === 'failed' ? 1 : 0;
+    }
+    finally {
+        process.removeListener('SIGINT', onSig);
+        process.removeListener('SIGTERM', onSig);
+        live.stop();
+        data.close();
+    }
+}
+function statusCmd(argv, io, home, now) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const ref = pos[0];
+    const tests = ref ? [findForwardTest(home, ref, now())].filter((x) => !!x) : listForwardTests(home).slice(0, 20);
+    if (ref && !tests.length) {
+        err(io, `no forward test for ${JSON.stringify(ref)}`);
+        return 1;
+    }
+    const rows = tests.map((t) => ({ forwardId: t.forwardId, strategy: t.strategyId, version: t.version, state: liveState(t, now()), source: t.source, window: windowText(t.window), startedAt: t.startedAt, endsAt: t.endsAt, progress: t.progress, endReason: t.endReason }));
+    if (opts.json) {
+        out(io, JSON.stringify({ paper: true, tests: rows }, null, 2));
+        return 0;
+    }
+    if (!rows.length) {
+        out(io, 'no forward tests yet (dexterm autotrade forward start <id> --hours 24)');
+        return 0;
+    }
+    for (const r of rows) {
+        const p = r.progress;
+        out(io, `${r.forwardId}  ${r.strategy.padEnd(18)} v${r.version}  ${r.state.toUpperCase().padEnd(8)} ${r.window}${p ? ` · ${p.closed} closed, ${p.open} open, equity $${p.equityUsd.toFixed(2)}` : ''}${r.endReason ? ` · ${r.endReason}` : ''}${r.source === 'live' ? '' : ` · ${r.source}`}`);
+    }
+    return 0;
+}
+function reportCmd(argv, io, home, now) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const ref = pos[0];
+    if (!ref) {
+        err(io, 'usage: dexterm autotrade forward report <id|fid> [--json]');
+        return 2;
+    }
+    let t = findForwardTest(home, ref, now());
+    if (!t) {
+        err(io, `no forward test for ${JSON.stringify(ref)}`);
+        return 1;
+    }
+    if (liveState(t, now()) === 'lost')
+        t = markLost(home, t, now());
+    const r = forwardReport(home, t, now());
+    if (opts.json) {
+        out(io, JSON.stringify({ paper: true, ...r }, null, 2));
+        return 0;
+    }
+    for (const l of r.lines)
+        out(io, l);
+    return 0;
+}

package/dist/packages/cli/src/autotrade-cmd/journey.js

@@ -0,0 +1,208 @@
+// `dexterm autotrade journey` and `dexterm autotrade promote` (0.2.0 card C): a strategy's ladder, and the user's side
+// of a promotion.
+//
+//   draft -> backtested -> forward-tested -> always-on (paper) -> real
+//
+// `journey [<id>]` shows where each strategy stands and what the next rung needs. `promote <id> --to always-on|real`
+// writes a promotion proposal (the analyst writes the same file with strategy_promote_propose) and shows its evidence
+// card; `promote list|show|apply|dismiss` resolve them. Applying always-on needs `y` typed on a real terminal (never a
+// pipe, a flag or an agent) and adds the strategy to autotrade.json as a paper member of the always-on service.
+// Real is never applied here: it hands over to `dexterm autotrade signal arm` (the evidence panel, the user's own
+// caps, a typed phrase with a one-time code), and refuses until the user has set the real-mode caps themselves.
+// No rung can be skipped on this path. task-1679: real also needs the evidence floor (a completed forward test with
+// the user's minForwardTrades closed paper trades + a backtest); below it `promote --to real` refuses and says how the
+// user alone can override it (`signal arm`, a typed OVERRIDE phrase on a real terminal, journaled).
+import { dextermHome } from '../../../custom/src/index.js';
+import { PromotionFiles, applyAlwaysOn, checkPromotion, dismissPromotion, findForwardTest, isActive, isPromotionId, journeyView, loadArmings, loadCaps, proposePromotion, renderJourney, windowText, } from '../../../autotrade/src/index.js';
+import { parseArgs, storeFor } from "./strategies.js";
+import { signalCmd } from "./signal.js";
+const BOOL = ['json'];
+export const JOURNEY_USAGE = 'dexterm autotrade journey [<id>] [--json]';
+export const PROMOTE_USAGE = [
+    'dexterm autotrade promote <id> --to always-on|real',
+    'dexterm autotrade promote list [--json] | show <pp-id> | apply <pp-id> | dismiss <pp-id>',
+].join('\n');
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, cmd, s) => { io.stderr.write(`dexterm autotrade ${cmd}: ${s}\n`); };
+function viewOf(io, id) {
+    const home = dextermHome(io.env);
+    const got = storeFor(io).get(id);
+    if (!got)
+        return { error: `no strategy ${JSON.stringify(id)} (dexterm autotrade list)` };
+    if (!got.ok)
+        return { error: `${id} does not validate: ${got.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}` };
+    return { s: got.strategy, v: journeyView(home, got.strategy, { armedHash: loadArmings(home)[id]?.strategyHash ?? null }) };
+}
+export function journeyCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const home = dextermHome(io.env);
+    const store = storeFor(io);
+    if (!pos[0]) {
+        const rows = store.list().filter((e) => e.source === 'user' && e.ok).map((e) => { const r = viewOf(io, e.id); return 'error' in r ? null : r.v; }).filter((v) => !!v);
+        if (opts.json) {
+            out(io, JSON.stringify({ paper: true, strategies: rows.map((v) => ({ id: v.id, version: v.version, stage: v.stage, next: v.next?.stage ?? null })) }, null, 2));
+            return 0;
+        }
+        if (!rows.length) {
+            out(io, 'no strategies of your own yet: copy a preset (dexterm autotrade new my-scalp --from scalp) or ask the analyst to build one');
+            return 0;
+        }
+        for (const v of rows)
+            out(io, `${v.id.padEnd(20)} v${v.version.padEnd(8)} ${v.stage.toUpperCase().padEnd(15)} ${v.next ? `next: ${v.next.stage}` : 'top of the ladder'}`);
+        return 0;
+    }
+    const r = viewOf(io, pos[0]);
+    if ('error' in r) {
+        err(io, 'journey', r.error);
+        return 1;
+    }
+    const fw = findForwardTest(home, r.s.id);
+    const running = fw && isActive(fw) ? fw : null;
+    const pending = new PromotionFiles(home).list({ status: 'pending', id: r.s.id });
+    if (opts.json) {
+        out(io, JSON.stringify({ paper: r.s.mode !== 'real', ...r.v, forwardRunning: running ? { forwardId: running.forwardId, window: running.window, progress: running.progress } : null, pendingPromotions: pending.map((p) => ({ proposalId: p.proposalId, to: p.to, actor: p.actor })) }, null, 2));
+        return 0;
+    }
+    for (const l of renderJourney(r.v))
+        out(io, l);
+    if (running)
+        out(io, `  forward test running: ${running.forwardId} · window ${windowText(running.window)}${running.progress ? ` · ${running.progress.closed} closed, ${running.progress.open} open` : ''}`);
+    for (const p of pending)
+        out(io, `  pending promotion ${p.proposalId} → ${p.to} (proposed by ${p.actor}): dexterm autotrade promote show ${p.proposalId}`);
+    return 0;
+}
+function isTty(io, deps) { return deps.tty ?? io.stdin?.isTTY === true; }
+async function typedLine(io, deps, prompt) {
+    if (deps.typed)
+        return deps.typed(prompt);
+    io.stderr.write(prompt);
+    const stdin = io.stdin;
+    if (!stdin)
+        return null;
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: stdin, terminal: false });
+    try {
+        return await new Promise((resolve) => { rl.once('line', (l) => resolve(l)); rl.once('close', () => resolve(null)); });
+    }
+    finally {
+        rl.close();
+        stdin.pause?.();
+    }
+}
+function showCard(io, p) {
+    out(io, `promotion ${p.proposalId} · ${p.status.toUpperCase()} · proposed by ${p.actor} · ${new Date(p.createdAt).toISOString().slice(0, 16).replace('T', ' ')}`);
+    out(io, `  why (as given, display only): ${p.why}`);
+    for (const l of p.card)
+        out(io, l);
+}
+export async function promoteCmd(argv, io, deps = {}) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const home = dextermHome(io.env);
+    const files = new PromotionFiles(home);
+    const now = deps.now ?? Date.now;
+    const sub = pos[0];
+    if (!sub || sub === 'help') {
+        out(io, PROMOTE_USAGE);
+        return sub ? 0 : 2;
+    }
+    if (sub === 'list') {
+        const all = files.list().slice(0, 30);
+        if (opts.json) {
+            out(io, JSON.stringify({ promotions: all.map(({ card: _c, ...p }) => p) }, null, 2));
+            return 0;
+        }
+        if (!all.length) {
+            out(io, 'no promotion proposals');
+            return 0;
+        }
+        for (const p of all)
+            out(io, `${p.proposalId}  ${p.id.padEnd(20)} → ${p.to.padEnd(9)} ${p.status.padEnd(9)} by ${p.actor}`);
+        return 0;
+    }
+    if (sub === 'show' || sub === 'apply' || sub === 'dismiss') {
+        const pid = pos[1];
+        const p = isPromotionId(pid) ? files.get(pid) : null;
+        if (!p) {
+            err(io, 'promote', `no promotion ${JSON.stringify(pid ?? '')} (dexterm autotrade promote list)`);
+            return 1;
+        }
+        if (sub === 'show') {
+            showCard(io, p);
+            return 0;
+        }
+        if (p.status !== 'pending') {
+            err(io, 'promote', `${p.proposalId} is ${p.status}`);
+            return 1;
+        }
+        if (sub === 'dismiss') {
+            dismissPromotion(home, p.proposalId, 'user', now());
+            out(io, `dismissed ${p.proposalId}; nothing changed`);
+            return 0;
+        }
+        return applyCmd(io, deps, p, now);
+    }
+    // promote <id> --to always-on|real: the user's own proposal, then straight to the confirm.
+    const id = sub;
+    const to = typeof opts.to === 'string' ? opts.to : '';
+    const r = viewOf(io, id);
+    if ('error' in r) {
+        err(io, 'promote', r.error);
+        return 1;
+    }
+    const armedHash = loadArmings(home)[id]?.strategyHash ?? null;
+    const c = checkPromotion(home, r.s, to, { armedHash });
+    if (!c.ok) {
+        err(io, 'promote', c.why);
+        if (c.view)
+            for (const l of renderJourney(c.view))
+                io.stderr.write(`${l}\n`);
+        if (c.reason === 'evidence-floor')
+            io.stderr.write(`  the floor is your limit minForwardTrades (dexterm autotrade limits explain minForwardTrades). To arm below it anyway, your call alone: dexterm autotrade signal arm ${id} on your own terminal asks for a typed OVERRIDE phrase, which is journaled.\n`);
+        return 1;
+    }
+    const made = proposePromotion(home, r.s, to, { actor: 'user', why: 'asked on the command line', now: now(), armedHash });
+    if (!made.ok) {
+        err(io, 'promote', made.why);
+        return 1;
+    }
+    return applyCmd(io, deps, made.proposal, now);
+}
+async function applyCmd(io, deps, p, now) {
+    const home = dextermHome(io.env);
+    const r = viewOf(io, p.id);
+    if ('error' in r) {
+        err(io, 'promote', r.error);
+        return 1;
+    }
+    if (r.s.hash !== p.hash) {
+        err(io, 'promote', `${p.id} changed since the proposal (v${p.version} → v${r.s.version}); dismiss it and ask for a new one`);
+        return 1;
+    }
+    showCard(io, p);
+    if (p.to === 'real') {
+        // Caps are the user's: real is only reachable here once the user set them on purpose (task-1655: card E's limits.json).
+        const caps = loadCaps(home);
+        if (!caps.ok) {
+            err(io, 'promote', `set your own real-mode caps first (your limits: dexterm autotrade limits set perTradeSol=X dailySol=Y buysPerDay=N maxOpenPositions=N, or signal caps set); ${caps.why}`);
+            return 1;
+        }
+        out(io, `real mode is armed by card A's typed confirmation; handing over to: dexterm autotrade signal arm ${p.id}`);
+        return signalCmd(['arm', p.id], io, deps);
+    }
+    if (!isTty(io, deps)) {
+        err(io, 'promote', 'applying a promotion needs your y on a real terminal (a pipe, a flag or an agent cannot give it); or apply it on the Q screen');
+        return 1;
+    }
+    const got = await typedLine(io, deps, `add ${p.id} to the always-on service (paper)? type y to apply, anything else cancels: `);
+    if ((got ?? '').trim().toLowerCase() !== 'y') {
+        err(io, 'promote', 'not applied; nothing changed (the proposal stays pending)');
+        return 1;
+    }
+    const a = applyAlwaysOn(home, p.proposalId, r.s, { by: 'user', now: now() });
+    if (!a.ok) {
+        err(io, 'promote', a.why);
+        return 1;
+    }
+    out(io, `applied: ${p.id} is ${a.created ? 'now' : 'again'} an always-on paper member (${a.memberId}) in autotrade.json. The service runs it from its next start: dexterm autotrade service status (restart it to pick it up now: service stop, then service start)`);
+    return 0;
+}