mindvest-atlas 0.58.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindvest-atlas",
-  "version": "0.58.0",
+  "version": "0.63.0",
   "description": "Atlas CLI \u2014 OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API",
   "type": "module",
   "bin": {

package/src/commands/alerts.js

@@ -1,11 +1,25 @@
 // `atlas alerts` — subscribe to the live alert-fire SSE feed, print each fire,
 // and optionally decode the attached chart PNG to a file.
+//
+// ONE STREAM PER COMPUTER, and it outlives the terminal. Both are in
+// `background`: a second stream would hand a reader every event twice, and a
+// stream that dies with the window is the wrong lifetime for something whose
+// job is to be there when an alert fires. `--detach` puts it in its own
+// session, `--stop` ends it, and a plain `atlas alerts` is refused while one is
+// already up.
 import fs from 'node:fs';
 import path from 'node:path';
 import { API } from '../config.js';
 import { runStream } from '../util/stream-loop.js';
 import { formatAlert } from '../util/format.js';
 import { color, println, eprintln } from '../util/ui.js';
+import * as background from '../util/background.js';
+
+// Names the slot, the claim file and the log, and it is the command's own name
+// so the advice this prints ("atlas alerts --stop") is always the truth.
+const SLOT = 'alerts';
+
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
 
 function sanitizeFilename(name) {
   return String(name || '').replace(/[^A-Za-z0-9._-]/g, '_') || 'alert.png';
@@ -13,6 +27,21 @@ function sanitizeFilename(name) {
 
 export async function alertsCommand(args) {
   const flags = args.flags;
+  if (flags.stop) return background.stop(SLOT);
+  if (flags.detach) return background.detach(SLOT);
+  const holder = background.holdUntilStopped(SLOT);
+  if (holder) {
+    background.alreadyRunning(SLOT, holder);
+    return 1;
+  }
+  try {
+    return await stream(flags);
+  } finally {
+    background.release(SLOT);
+  }
+}
+
+async function stream(flags) {
   const qs = new URLSearchParams();
   if (flags.symbol) qs.set('symbol', String(flags.symbol).toUpperCase());
   const name = flags.name || flags.type || flags['alert-type'];
@@ -20,8 +49,18 @@ export async function alertsCommand(args) {
   // --no-chart (flags.chart === false) suppresses chart payloads server-side.
   if (flags.chart === false || flags['no-chart']) qs.set('chart', '0');
 
-  const saveDir = (typeof flags['save-charts'] === 'string' && flags['save-charts'])
+  let saveDir = (typeof flags['save-charts'] === 'string' && flags['save-charts'])
     || (typeof flags.out === 'string' && flags.out);
+  // DETACHED, THE CHARTS NEED SOMEWHERE TO GO. With no terminal there is nobody
+  // to have passed --save-charts, and the alternative is that every chart lives
+  // only as base64 inside a log that the size cap then rolls away. So a
+  // background stream saves them beside its log unless it was told not to fetch
+  // charts at all, or told where to put them.
+  let ownDir = false;
+  if (!saveDir && qs.get('chart') !== '0' && background.isBackground(SLOT)) {
+    saveDir = background.chartsDir(SLOT);
+    ownDir = true;
+  }
   if (saveDir) fs.mkdirSync(saveDir, { recursive: true });
 
   const json = !!flags.json;
@@ -31,23 +70,40 @@ export async function alertsCommand(args) {
     eprintln(color.dim('Listening for alert fires' + (flags.symbol ? ` on ${String(flags.symbol).toUpperCase()}` : '') + (name ? ` (${name})` : '') + '…'));
   }
 
-  return runStream(pathname, {
+  const onStream = {
     label: 'alerts',
     // `--no-reconnect` parses to flags.reconnect === false (the --no- convention).
     reconnect: flags.reconnect !== false,
     onEvent: ({ event, payload }) => {
       // Decode + save the chart if present and requested.
+      let saved = null;
       if (saveDir && payload.chart && payload.chart.image_base64) {
-        const file = path.join(saveDir, sanitizeFilename(payload.chart.filename));
+        // The server names every chart after its alert ("alert_SPY.png"), so in
+        // a stream that runs for months each fire would overwrite the one before
+        // it and only the latest per symbol would survive. A stamp in front
+        // keeps them all. Only in our OWN directory: somebody who passed
+        // --save-charts is relying on the name they already get.
+        let base = sanitizeFilename(payload.chart.filename);
+        if (ownDir) base = `${new Date().toISOString().replace(/[-:]/g, '').slice(0, 15)}_${base}`;
+        const file = path.join(saveDir, base);
         try {
           fs.writeFileSync(file, Buffer.from(payload.chart.image_base64, 'base64'));
+          saved = file;
           if (!json) eprintln(color.green('  ↳ chart saved: ') + file);
         } catch (err) {
           eprintln(color.red('  ↳ could not save chart: ') + err.message);
         }
+        if (ownDir) background.pruneDir(background.chartsDir(SLOT));
       }
 
       if (json) {
+        // The picture is already on disk, so the line points AT it instead of
+        // carrying a second copy as base64. That is what keeps a JSON log small
+        // enough to be worth keeping.
+        if (saved) {
+          const { image_base64: _drop, ...rest } = payload.chart;
+          payload = { ...payload, chart: { ...rest, file: saved } };
+        }
         println(JSON.stringify(payload));
         return;
       }
@@ -56,5 +112,20 @@ export async function alertsCommand(args) {
         for (const b of payload.bullets) println('  ' + color.dim(b));
       }
     },
-  });
+  };
+
+  if (flags.reconnect === false) return runStream(pathname, onStream);
+
+  // RUNS UNTIL SOMEBODY STOPS IT. runStream RETURNS only when it has given up,
+  // and it gives up on things that pass: an expired sign-in whose refresh
+  // happened to fail, a refusal from the server. A stream that is detached,
+  // with nobody watching the terminal, must not end for good on one of those -
+  // it would sit there dead and nothing would say so. A clean stop (Ctrl-C, or
+  // `--stop`) is the only thing that ends this loop.
+  for (;;) {
+    const code = await runStream(pathname, onStream);
+    if (code === 0) return 0;
+    eprintln(color.yellow('● the feed stopped. Trying again in a minute.'));
+    await sleep(60_000);
+  }
 }

package/src/commands/remote-control.js

@@ -195,7 +195,9 @@ async function handleAsk(ask, root) {
         else if (ask.op === 'publish') {
           out = await sharing.publish(ask.job || '', root, {
             name: ask.name, description: ask.description || '', notes: ask.notes || '',
-            asNew: Boolean(ask.as_new), force: Boolean(ask.force),
+            asNew: (ask.as_new === undefined || ask.as_new === null)
+              ? null : Boolean(ask.as_new),
+            force: Boolean(ask.force),
             exclude: ask.exclude,
           });
         } else if (ask.op === 'unshare') out = await sharing.unpublish(ask.job || '', root);

package/src/commands/share.js

@@ -49,7 +49,8 @@ const SUB_HELP = `atlas share <state|publish|off|peek|file|install|updates|fetch
 
   state    --job <name>                 is this project shared, and its link
   publish  --job <name> [--notes …]     put the current files out as a new version
-           [--as-new] [--force] [--name …] [--description …]
+           [--as-new | --same] [--force] [--name …] [--description …]
+           --as-new: a different project. --same: the one you already share.
            [--hold-back runs,notes.md]  files to leave out (kept in atlas.json)
   off      --job <name>                 stop sharing; the link stops working
   peek     --link <id:token>            download and describe, without installing
@@ -78,7 +79,8 @@ export async function shareCommand(args) {
         name: flag(args, 'name'),
         description: String(flag(args, 'description') || ''),
         notes: String(flag(args, 'notes') || ''),
-        asNew: Boolean(flag(args, 'as-new', 'as_new', 'new')),
+        asNew: flag(args, 'as-new', 'as_new', 'new') ? true
+          : (flag(args, 'same', 'existing') ? false : null),
         force: Boolean(flag(args, 'force')),
         exclude: holdBack(args),
       });

package/src/config.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import os from 'node:os';
 
-export const VERSION = '0.58.0';
+export const VERSION = '0.63.0';
 export const DEFAULT_BASE_URL = 'https://atlasmcp.finmanagerai.com';
 export const DEFAULT_SCOPE = 'atlas broker';
 export const CLIENT_NAME = 'Atlas CLI';

package/src/helpers/atlas_env.js

@@ -167,10 +167,27 @@ export async function* alerts({ match = null, timeoutMs = null, reconnect = true
   const deadline = timeoutMs == null ? null : Date.now() + Number(timeoutMs);
   let attempt = 0;
   while (deadline == null || Date.now() < deadline) {
+    let quiet = null;
+    let untilDeadline = null;
     try {
+      // TWO DIFFERENT CLOCKS, and only one of them was here before. The
+      // deadline is how long the CALLER still wants to wait. The watchdog is
+      // how long SILENCE is allowed on a feed that is meant to be up: without
+      // it a half-open socket (a laptop that slept, a NAT that dropped the
+      // mapping) never errors and never delivers, so the read below waits for
+      // ever on a connection that is already dead, the job looks alive, and no
+      // alert arrives again. A keepalive lands every 20s, so a minute of
+      // nothing means gone and the reconnect underneath gets its turn.
+      const ac = new AbortController();
+      const heard = () => {
+        if (quiet) clearTimeout(quiet);
+        quiet = setTimeout(() => ac.abort(), 60000);
+      };
+      if (deadline != null) untilDeadline = setTimeout(() => ac.abort(), Math.max(1, deadline - Date.now()));
+      heard();
       const res = await fetch(`${base}/api/v1/alerts?chart=0`, {
         headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
-        signal: deadline == null ? undefined : AbortSignal.timeout(Math.max(1, deadline - Date.now())),
+        signal: ac.signal,
       });
       if (!res.ok || !res.body) throw new Error(`alerts feed ${res.status}`);
       attempt = 0;
@@ -180,6 +197,7 @@ export async function* alerts({ match = null, timeoutMs = null, reconnect = true
       for (;;) {
         const { done, value } = await reader.read();
         if (done) break;
+        heard();                    // it spoke, so the silence starts over
         buffer += decoder.decode(value, { stream: true });
         let cut;
         // A BLANK LINE ENDS A FRAME. Both endings, because a feed read on
@@ -210,6 +228,9 @@ export async function* alerts({ match = null, timeoutMs = null, reconnect = true
       if (deadline != null) nap = Math.min(nap, Math.max(0, deadline - Date.now()));
       if (nap <= 0) return;
       await new Promise((r) => setTimeout(r, nap));
+    } finally {
+      if (quiet) clearTimeout(quiet);
+      if (untilDeadline) clearTimeout(untilDeadline);
     }
   }
 }

package/src/helpers/atlas_env.py

@@ -226,8 +226,19 @@ def alerts(match=None, timeout=None, reconnect=True):
                 base + "/api/v1/alerts?chart=0",
                 headers={"Authorization": "Bearer " + token, "Accept": "text/event-stream"},
             )
+            # TWO DIFFERENT CLOCKS, and only one of them was here before.
+            # `left` is how long the CALLER still wants to wait. The read
+            # timeout is how long SILENCE is allowed on a feed that is supposed
+            # to be up, and without it a half-open socket - a laptop that
+            # slept, a NAT that dropped the mapping, a load balancer that
+            # reaped an idle connection - never raises and never delivers: the
+            # loop below blocks for ever on a connection that is already dead,
+            # the job looks alive, and no alert ever arrives again. The feed
+            # sends a keepalive every 20s, so a minute of nothing means gone,
+            # and the reconnect underneath finally gets its turn.
             left = None if deadline is None else max(1, deadline - _time.time())
-            with urllib.request.urlopen(req, timeout=left) as r:
+            quiet = 60 if left is None else min(left, 60)
+            with urllib.request.urlopen(req, timeout=quiet) as r:
                 attempt = 0
                 kind, data = "", []
                 for raw in r:
@@ -2421,7 +2432,7 @@ def _sleep_or_stop(seconds, slice_s=1.0):
     return _still_mine()
 
 
-def watch(instruction, every=5, most=200, hours=8, look=True):
+def watch(instruction, every=5, most=200, hours=8, look=True, model=""):
     """Watch the screen and act when it is time. Runs until it is done.
 
     THE SHAPE OF A JOB THAT IS MOSTLY WAITING (owner, 2026-09-06: "watch this
@@ -2454,6 +2465,24 @@ def watch(instruction, every=5, most=200, hours=8, look=True):
     choosing, and why a model that says "nothing is happening, look again in an
     hour" is doing its job rather than being lazy.
 
+    A SMALL MODEL CAN DO THE WATCHING (owner, 2026-09-10: "a smaller model to
+    watch continuously, then the router is able to route to larger to call tools
+    and do other stuff"). `model=` names who is asked each round, and the round
+    is the cheap half of this: nothing has changed, look again later. It is the
+    ACTING that wants a big model, and the watcher hands that over the same way
+    anything else does, by calling ask() with one:
+
+        watch("Watch the SPY 5-minute chart. Say QUIET and nothing else while "
+              "it is quiet. When the opening range high breaks on rising "
+              "volume, call: "
+              "  ask('Break just happened, here is the screen: <path>. Decide "
+              "      the trade and place it.', model='claude-opus-5')",
+              every=2, model="claude-haiku-4-5")
+
+    Whoever is watching still has this whole computer, so a watcher that can
+    decide for itself should just act. Route when the decision is worth the
+    bigger model, not on principle. models() lists what this machine can reach.
+
     Ends when the model writes DONE on a line by itself, when `most` rounds have
     passed, or when `hours` have. Pressing Stop ends it like anything else.
     """
@@ -2523,7 +2552,7 @@ def watch(instruction, every=5, most=200, hours=8, look=True):
                    else "The screen could not be photographed this round.")
             )
             try:
-                answer = ask(asked)
+                answer = ask(asked, model=model)
             except Exception as err:
                 answer = ""
                 seen.append({"round": rounds, "error": str(err)})

package/src/sharing.js

@@ -287,6 +287,35 @@ export function describeProject(dir) {
   return '';
 }
 
+/**
+ * Settings in `atlas.json` that describe the AUTHOR's publishing rather than
+ * the project's behaviour. They are theirs, they mean nothing in a copy, and
+ * they are the shape of remnant nobody would think to look for: an importer
+ * opening the share dialog on their own copy found the author's ticks already
+ * in it, holding back files they had never chosen to hold back.
+ *
+ * The schedule, the run line and `on_alert` are NOT here: those are what the
+ * project DOES, and a copy that did not do it would not be a copy.
+ */
+const AUTHOR_ONLY_SETTINGS = [EXCLUDE_KEY];
+
+/**
+ * One file's bytes as they should arrive in somebody else's project.
+ *
+ * Only `atlas.json` is touched, and only to drop the author's own publishing
+ * settings. Anything unreadable passes through untouched: a file we cannot
+ * parse is a file we have no business editing.
+ */
+function forTheCopy(rel, data) {
+  if (rel !== 'atlas.json') return data;
+  let raw;
+  try { raw = JSON.parse(data.toString('utf8')); } catch { return data; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return data;
+  if (!AUTHOR_ONLY_SETTINGS.some((k) => k in raw)) return data;
+  for (const key of AUTHOR_ONLY_SETTINGS) delete raw[key];
+  return Buffer.from(JSON.stringify(raw, null, 2));
+}
+
 export function packProject(job, root, { name, description = '', exclude } = {}) {
   const dir = projectDir(job, root);
   if (!fs.existsSync(dir)) return { ok: false, error: `There is no project called ${job} here.` };
@@ -303,6 +332,10 @@ export function packProject(job, root, { name, description = '', exclude } = {})
   for (const rel of files) {
     let data;
     try { data = fs.readFileSync(path.join(dir, rel)); } catch { continue; }
+    // Hashed AFTER, so the manifest describes what actually arrives — an update
+    // comparing against a hash of something else would report every copy as
+    // locally modified.
+    data = forTheCopy(rel, data);
     hashes[rel] = sha(data);
     entries.push({ name: rel, data });
   }
@@ -321,7 +354,7 @@ export function packProject(job, root, { name, description = '', exclude } = {})
 // ── publishing ─────────────────────────────────────────────────────────────
 
 export async function publish(job, root, {
-  name, description = '', notes = '', asNew = false, force = false, exclude,
+  name, description = '', notes = '', asNew = null, force = false, exclude,
 } = {}) {
   const dir = projectDir(job, root);
   // The choice is REMEMBERED before it is used, so the next publish holds the
@@ -332,6 +365,27 @@ export async function publish(job, root, {
   if (!packed.ok) return packed;
 
   const pin = readPin(dir) || {};
+  // WHOSE PACKAGE THIS PUBLISH IS A VERSION OF.
+  //
+  // `.atlas-source.json` answers two questions with one field: on the author's
+  // own folder `package_id` is "the package I publish", on an IMPORTED copy it
+  // is "the package I came from", which belongs to somebody else. Sending it
+  // either way asked the server to publish a new version of a stranger's
+  // package and came back "That package is not yours, or no longer exists" —
+  // a refusal about ownership, worded as if the project had vanished (owner
+  // report 2026-09-09; "this should create its own link").
+  //
+  // A copy you have changed is your own work built on theirs: it publishes as
+  // YOUR package, under your own link, with where it came from recorded rather
+  // than pretended away.
+  const mine = Boolean(pin.author) || !pin.package_id;
+  const upstream = mine ? null : {
+    package_id: pin.package_id,
+    version: pin.version,
+    share: pin.share,
+    name: pin.name,
+    author_name: pin.author_name,
+  };
   const fields = {
     slug: path.basename(dir),
     name: name || pin.name || path.basename(dir),
@@ -344,9 +398,14 @@ export async function publish(job, root, {
     machine_id: machineId(),
     machine_name: computerName(),
   };
-  if (pin.package_id) fields.package_id = String(pin.package_id);
-  if (pin.version) fields.base_version = String(pin.version);
-  if (asNew) fields.as_new = 'true';
+  // Only an author's own pin names the package being versioned. A copy has no
+  // package of its own yet, so it asks for one.
+  if (mine && pin.package_id) fields.package_id = String(pin.package_id);
+  if (mine && pin.version) fields.base_version = String(pin.version);
+  // Three-valued: null = nobody has been asked yet (the server may come back
+  // with the slug conflict), true = "a new project", false = "yes, that one —
+  // publish its next version". Sent only when there IS an answer.
+  if (asNew !== null && asNew !== undefined) fields.as_new = asNew ? 'true' : 'false';
   if (force) fields.force = 'true';
 
   let status; let data;
@@ -376,13 +435,24 @@ export async function publish(job, root, {
     // button has a LINK to offer, not a line of hex.
     share_url: data.share_url,
     name: fields.name,
+    // WHAT THE PROJECT IS, KEPT (owner, 2026-09-09: "when publishing changes,
+    // it always ask what the project is for — if the user has added this just
+    // recall it"). It was sent to the server and forgotten locally, so the
+    // publish dialog opened with an empty box on every single release and the
+    // author retyped the same sentence or, more often, shipped without one.
+    description: fields.description,
     author: true,
+    // Where it started, kept for as long as the copy exists. Provenance, not a
+    // subscription: the update check follows `package_id`, which is now this
+    // person's own package.
+    ...(upstream ? { forked_from: upstream } : {}),
     files: packed.manifest.files,
     at: Math.floor(Date.now() / 1000),
   });
   return {
     ok: true, share: data.share, share_url: data.share_url, package_id: data.package_id,
     version: data.version, requires: packed.manifest.requires,
+    ...(upstream ? { forked_from: upstream } : {}),
   };
 }
 
@@ -454,9 +524,16 @@ export function shareState(job, root) {
     share: pin.share,
     package_id: pin.package_id,
     version: pin.version,
-    // An imported copy is somebody else's project: updatable, never publishable.
+    // Whether this folder is the one YOU publish. An imported copy starts
+    // False; publishing it makes a package of your own and flips it. Not a lock
+    // on the button — a copy you have changed is your own work, and the link it
+    // gets is your own.
     mine: Boolean(pin.author),
     author_name: pin.author_name,
+    forked_from: pin.forked_from,
+    // What this project IS, as last published. The publish dialog seeds its
+    // box from here, so a re-release starts with the sentence already in it.
+    description: pin.description,
   };
 }
 
@@ -595,6 +672,46 @@ function extract(zipPath, target, priorHashes) {
   return { written, kept, backed };
 }
 
+/**
+ * Empty a folder into `.atlas-backup/<ts>/`, and say what moved.
+ *
+ * A COPY ARRIVES UNSEEDED (owner rule 2026-09-09: "when someone sends a copy,
+ * or when they fork out, let everything be unseeded — there is an issue where
+ * the seeding is even affecting the keys").
+ *
+ * An install used to write the package's files ON TOP of whatever was already
+ * in the folder and remove nothing, so a project taking the name of one that
+ * was there before inherited it: its leftover scripts, its `runs/`, its
+ * `trades.json`, its `atlas.json` schedule — and its `.env`, which is how a
+ * brand-new copy came up already holding somebody else's keys. Files the
+ * package happened to also contain were replaced; everything else stayed,
+ * mixed in and indistinguishable from the copy itself.
+ *
+ * So a NEW project starts on an empty folder. Nothing is deleted — the old
+ * contents move, whole, into `.atlas-backup/<ts>/`, which is where this module
+ * already puts anything it would otherwise overwrite — and the backup folder
+ * itself stays put, so a second import never buries the first.
+ *
+ * An UPDATE of the same package does NOT come through here: keeping your keys
+ * and your edits across an update is the entire point of the pin.
+ */
+function sweepAside(target) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const keep = path.join(target, BACKUP_DIR, stamp);
+  const moved = [];
+  let entries = [];
+  try { entries = fs.readdirSync(target).sort(); } catch { return moved; }
+  for (const name of entries) {
+    if (name === BACKUP_DIR) continue;   // where things go; never a thing that goes
+    try {
+      fs.mkdirSync(keep, { recursive: true });
+      fs.renameSync(path.join(target, name), path.join(keep, name));
+      moved.push(name);
+    } catch { /* unmovable (locked, in use) — one leftover, not a failed install */ }
+  }
+  return moved;
+}
+
 export function install(packageId, root, { job } = {}) {
   const stage = stagingDir(root, packageId);
   const zipPath = path.join(stage, 'package.zip');
@@ -609,10 +726,18 @@ export function install(packageId, root, { job } = {}) {
 
   const slug = safeSlug(job || manifest.slug || 'project');
   const target = projectDir(slug, root);
-  const prior = (readPin(target) || {}).files || {};
+  const pinBefore = readPin(target) || {};
+  let prior = pinBefore.files || {};
+  // AN UPDATE, or A NEW PROJECT LANDING HERE? The pin tells them apart: same
+  // package = the author published again and this copy moves forward (keys,
+  // edits and all). Anything else — no pin, or a pin for a different package —
+  // is a new project taking this folder, and it starts clean. See sweepAside.
+  const isUpdate = String(pinBefore.package_id || '') === String(packageId);
   try { fs.mkdirSync(target, { recursive: true }); } catch (err) {
     return { ok: false, error: `Could not make the folder: ${err.message}` };
   }
+  const swept = isUpdate ? [] : sweepAside(target);
+  if (swept.length) prior = {};   // nothing here came from this package
 
   let result;
   try { result = extract(zipPath, target, prior); } catch (err) {
@@ -637,6 +762,10 @@ export function install(packageId, root, { job } = {}) {
     written: result.written,
     kept: result.kept,
     backed_up: result.backed,
+    // What was in the folder before and is now in `.atlas-backup/`. Named so a
+    // screen can say it: somebody who had something here deserves to be told
+    // where it went, and somebody who did not sees an empty list.
+    moved_aside: swept,
     requires,
     missing_keys: missingKeys(target, requires, root),
   };

package/src/util/background.js

@@ -0,0 +1,385 @@
+// One named background process per computer: claim it, detach it, stop it.
+//
+// `atlas alerts` holds a live connection to the alert feed. Two things follow
+// from that, and this is where both are answered:
+//
+//   ONE AT A TIME. The stream is a thing you can act on, so a second one on the
+//   same computer is a second copy of every event: doubled lines in the log a
+//   reader is tailing, and doubled work in whatever reads it. The slot is
+//   CHECKED, never assumed - a claim whose process is gone, or that has not said
+//   it is here inside STALE_MS, is holding nothing, so a crash costs the next
+//   start no wait.
+//
+//   IT SHOULD OUTLIVE THE TERMINAL. A stream that dies when you close the
+//   window, or when you run another atlas command, is the wrong lifetime for
+//   something whose whole job is to be there when an alert fires. `--detach`
+//   gives it its own session; `--stop` ends it.
+//
+// State lives beside the CLI's own config, not in a workspace, because a stream
+// has nothing to do with any project folder.
+//
+// Mirror of python/atlas_cli/background.py.
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir } from '../config.js';
+import { color, println, eprintln } from './ui.js';
+
+/**
+ * This process, named. Regenerated every start, so a claim written by an
+ * EARLIER one is recognisable as belonging to a process that is gone.
+ */
+export const PROCESS_ID = `${Date.now()}-${process.pid}`;
+
+/** How often a background process says it is still here, and how long that is
+ *  worth believing. Three missed beats means it is not coming back. */
+export const BEAT_MS = 20_000;
+export const STALE_MS = 90_000;
+
+/** How large the log may get, and how often that is checked. A stream meant to
+ *  run for months writes for months, and an uncapped log is a disk that fills
+ *  up silently at 3am. */
+export const LOG_MAX_BYTES = Number(process.env.ATLAS_LOG_MAX_BYTES) || 16 * 1024 * 1024;
+export const LOG_CHECK_MS = 60_000;
+
+/** The same, for saved charts. One PNG per fire across every alert adds up. */
+export const CHARTS_MAX_BYTES = Number(process.env.ATLAS_CHARTS_MAX_BYTES) || 256 * 1024 * 1024;
+
+/** Set on the child `detach` starts, so it can tell it has no terminal: that is
+ *  what makes it keep its own log in check and save charts somewhere findable
+ *  rather than assuming a person is watching. */
+export const BACKGROUND_ENV = 'ATLAS_BACKGROUND';
+
+/** True inside the process `detach` started. */
+export function isBackground(name) {
+  const got = (process.env[BACKGROUND_ENV] || '').trim();
+  return !!got && (name === undefined || got === name);
+}
+
+export const chartsDir = (name) => path.join(configDir(), `${name}-charts`);
+
+/** How many full logs are kept behind the live one. Total on disk is therefore
+ *  bounded by LOG_MAX_BYTES * (LOG_KEEP + 1). */
+export const LOG_KEEP = 5;
+
+export const oldLog = (name, i) => path.join(configDir(), `${name}.${i}.log`);
+
+/**
+ * Full? Start a NEW file, and shift the old ones along.
+ *
+ * `alerts.log` is always the live one, `alerts.1.log` the last full one, and so
+ * on to LOG_KEEP, past which the oldest is dropped. So the name a reader tails
+ * never changes, and history stays in whole files instead of a window that
+ * keeps eating its own beginning.
+ *
+ * THE WRITER IS THIS PROCESS. Renaming alone would not be enough: our stdout is
+ * an append-mode fd on the file we just moved, so we would go on writing into
+ * `alerts.1.log` and the new `alerts.log` would stay empty for ever. Node has
+ * no dup2, but close(1) then open() hands back the lowest free descriptor,
+ * which IS 1 - that is what moves the writing.
+ */
+export function rollLog(name, cap = LOG_MAX_BYTES) {
+  const log = logFile(name);
+  try {
+    if (fs.statSync(log).size < cap) return false;
+  } catch {
+    return false;
+  }
+  try {
+    const oldest = oldLog(name, LOG_KEEP);
+    if (fs.existsSync(oldest)) fs.unlinkSync(oldest);
+    for (let i = LOG_KEEP - 1; i >= 1; i -= 1) {
+      const src = oldLog(name, i);
+      if (fs.existsSync(src)) fs.renameSync(src, oldLog(name, i + 1));
+    }
+    fs.renameSync(log, oldLog(name, 1));
+  } catch {
+    // Windows will not rename a file this process holds open. Falling back
+    // keeps the log bounded there too, just as a window rather than files.
+    return trimLog(log, cap);
+  }
+  // ONLY THE WRITER MOVES ITS OWN OUTPUT. These are fd 1 and 2 of THIS process,
+  // so anything else calling rollLog (a test, a tidy-up) would otherwise find
+  // its own stdout pointing into the log it just rolled.
+  if (isBackground(name)) {
+    for (const want of [1, 2]) {
+      try {
+        fs.closeSync(want);
+        const got = fs.openSync(log, 'a');
+        if (got !== want) {          // somebody took it first: do not write blind
+          fs.closeSync(got);
+          return true;
+        }
+      } catch { /* nothing more we can do about this descriptor */ }
+    }
+  }
+  return true;
+}
+
+/**
+ * Keep the END of the log and drop the beginning, IN PLACE.
+ *
+ * The fallback for when rolling is not possible (Windows holds the open file
+ * against a rename). The last line before the cut is dropped rather than left
+ * half-written, so a reader parsing one JSON object per line never meets a
+ * broken one.
+ */
+export function trimLog(file, cap = LOG_MAX_BYTES) {
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return false;
+  }
+  if (size <= cap) return false;
+  const keep = Math.floor(cap / 2);
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(keep);
+    fs.readSync(fd, buf, 0, keep, size - keep);
+    fs.closeSync(fd);
+    const cut = buf.indexOf(0x0a);
+    const tail = cut === -1 ? buf : buf.subarray(cut + 1);
+    fs.writeFileSync(file, Buffer.concat([
+      Buffer.from('... earlier lines dropped: the log passed its size cap ...\n'), tail,
+    ]));
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+/** Keep a directory under a size cap, oldest file first. */
+export function pruneDir(dir, cap = CHARTS_MAX_BYTES) {
+  let files;
+  try {
+    files = fs.readdirSync(dir).map((n) => {
+      const f = path.join(dir, n);
+      const st = fs.statSync(f);
+      return st.isFile() ? { f, mtime: st.mtimeMs, size: st.size } : null;
+    }).filter(Boolean);
+  } catch {
+    return 0;
+  }
+  let total = files.reduce((a, x) => a + x.size, 0);
+  if (total <= cap) return 0;
+  let dropped = 0;
+  for (const x of files.sort((a, b) => a.mtime - b.mtime)) {
+    if (total <= cap) break;
+    try {
+      fs.unlinkSync(x.f);
+      total -= x.size;
+      dropped += 1;
+    } catch { /* someone else got there first */ }
+  }
+  return dropped;
+}
+
+/** Keep this background process's own log under the cap, for as long as it runs. */
+export function startLogCap(name) {
+  const charts = chartsDir(name);
+  const t = setInterval(() => {
+    try {
+      rollLog(name);
+      if (fs.existsSync(charts)) pruneDir(charts);
+    } catch { /* tidying is never worth dying over */ }
+  }, LOG_CHECK_MS);
+  t.unref?.();
+}
+
+export const claimFile = (name) => path.join(configDir(), `${name}.json`);
+export const logFile = (name) => path.join(configDir(), `${name}.log`);
+
+/** {id, pid, beat} of whoever holds this slot, or null. */
+export function readClaim(name) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(claimFile(name), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || !raw.id) return null;
+  return { id: String(raw.id), pid: Number(raw.pid) || 0, beat: Number(raw.beat) || 0 };
+}
+
+function pidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';      // someone else's, but it exists
+  }
+}
+
+/**
+ * The OTHER process holding this slot right now, or null.
+ *
+ * HELD IS A CHECKED FACT. A file on disk only says somebody once started; it
+ * takes a live pid and a recent beat to say somebody is still going.
+ */
+export function heldByOther(name, nowMs = Date.now()) {
+  const info = readClaim(name);
+  if (!info || info.id === PROCESS_ID) return null;
+  if (nowMs - info.beat * 1000 > STALE_MS) return null;
+  if (info.pid && !pidAlive(info.pid)) return null;
+  return info;
+}
+
+/** Say this process is still here. False once the slot is somebody else's. */
+export function beat(name) {
+  if (heldByOther(name)) return false;
+  try {
+    const f = claimFile(name);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify({ id: PROCESS_ID, pid: process.pid, beat: Date.now() / 1000 }));
+  } catch { /* a beat that cannot be written is not fatal */ }
+  return true;
+}
+
+/** Take the slot, or return the holder that already has it. */
+export function claim(name, nowMs = Date.now()) {
+  const holder = heldByOther(name, nowMs);
+  if (holder) return holder;
+  beat(name);
+  // Two starts in the same instant can both find it free. The file ends up with
+  // one name in it, so read it back: whoever is not in it stands down.
+  const again = readClaim(name);
+  if (again && again.id !== PROCESS_ID) return again;
+  return null;
+}
+
+/** Give the slot up on the way out. Only ever ours to drop. */
+export function release(name) {
+  try {
+    const info = readClaim(name);
+    if (info && info.id !== PROCESS_ID) return;
+    fs.unlinkSync(claimFile(name));
+  } catch { /* nothing there to give up */ }
+}
+
+/**
+ * Claim the slot for this process and arrange to give it back.
+ *
+ * Returns the holder when the slot is taken (the caller should stop), or null
+ * once it is ours.
+ */
+export function holdUntilStopped(name) {
+  const holder = claim(name);
+  if (holder) return holder;
+  const go = () => { release(name); process.exit(0); };
+  process.once('SIGTERM', go);       // `--stop` asks with this
+  process.once('exit', () => release(name));
+  const t = setInterval(() => { try { beat(name); } catch { /* not fatal */ } }, BEAT_MS);
+  t.unref?.();                       // a heartbeat must not hold the process up
+  if (isBackground(name)) startLogCap(name);
+  return null;
+}
+
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+
+/**
+ * Run this same command again, off the terminal, and hand the prompt back.
+ *
+ * Same command, same flags, its own session, so nothing about how it behaves
+ * depends on having been detached.
+ *
+ * A pid is not a running stream. This waits for the child to CLAIM the slot
+ * before it says anything started, because "we spawned something" and "it is
+ * up" are different facts and only the second is worth printing.
+ */
+export async function detach(name, flag = '--detach') {
+  const holder = heldByOther(name);
+  if (holder) {
+    alreadyRunning(name, holder);
+    return 1;
+  }
+
+  const log = logFile(name);
+  let child;
+  let fd;
+  try {
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    fd = fs.openSync(log, 'a');
+    const argv = process.argv.slice(2).filter((a) => a !== flag && a !== `${flag}=true`);
+    child = spawn(process.execPath, [process.argv[1], ...argv], {
+      detached: true,                // its own session: closing the window
+      stdio: ['ignore', fd, fd],     // cannot hang it up
+      windowsHide: true,
+      env: { ...process.env, [BACKGROUND_ENV]: name },
+    });
+    child.unref();
+  } catch (err) {
+    eprintln(color.red(`Could not start it in the background: ${err.message}`));
+    return 1;
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* the child holds it now */ } }
+  }
+
+  let exited = false;
+  child.once('exit', () => { exited = true; });
+  const end = Date.now() + 15_000;
+  while (Date.now() < end) {
+    const info = readClaim(name);
+    if (info && info.pid === child.pid) {
+      println(color.green('Streaming in the background.') + color.dim(`  pid ${child.pid}`));
+      println(color.dim(`  Log:  ${log}`));
+      println(color.dim(`  Read: tail -f ${log}`));
+      println(color.dim(`  Stop: atlas ${name} --stop`));
+      return 0;
+    }
+    if (exited) break;               // it stopped instead of taking the slot
+    await sleep(200);
+  }
+  eprintln(color.red('It started but never took the slot.'));
+  eprintln(color.dim(`  What it wrote: ${log}`));
+  return 1;
+}
+
+/**
+ * Stop the background process holding this slot, detached or not.
+ *
+ * STOPPED IS A FACT WE CHECK, not one we assume: asking is not the same as it
+ * having happened. This waits for the slot to come free and says which of the
+ * two actually did.
+ */
+export async function stop(name) {
+  const holder = heldByOther(name);
+  if (!holder) {
+    println(color.dim('Nothing is streaming here.'));
+    return 0;
+  }
+  if (!holder.pid) {
+    eprintln(color.red('Something holds the slot but wrote no pid, so there is nothing '
+      + `to stop. It frees itself within ${STALE_MS / 1000}s.`));
+    return 1;
+  }
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('taskkill', ['/PID', String(holder.pid), '/T', '/F'], { stdio: 'ignore' });
+    } else {
+      process.kill(holder.pid, 'SIGTERM');
+    }
+  } catch (err) {
+    eprintln(color.red(`Could not stop pid ${holder.pid}: ${err.message}`));
+    return 1;
+  }
+  const end = Date.now() + 15_000;
+  while (Date.now() < end) {
+    if (heldByOther(name) === null) {
+      println(color.green('Stopped.') + color.dim(`  (pid ${holder.pid})`));
+      return 0;
+    }
+    await sleep(200);
+  }
+  eprintln(color.yellow(`Asked pid ${holder.pid} to stop, and it is still going after 15s.`));
+  return 1;
+}
+
+/** Say who has the slot, for a caller that has just been refused. */
+export function alreadyRunning(name, holder) {
+  eprintln(color.red('Already streaming on this computer.') + color.dim(`  pid ${holder.pid}`));
+  eprintln(color.dim('  One stream at a time, so a reader never sees an event twice.'));
+  eprintln(color.dim(`  Stop it with: atlas ${name} --stop`));
+  eprintln(color.dim(`  Or watch what it writes: tail -f ${logFile(name)}`));
+}

package/src/util/help.js

@@ -30,6 +30,7 @@ export function printRootHelp() {
   println(c.bold('STREAMS'));
   println('  alerts [--symbol SPY] [--name greek_exposure]      Live alert feed (SSE)');
   println('         [--save-charts <dir>] [--no-chart] [--json]');
+  println('         [--detach] [--stop]                        Stream in the background, or stop it');
   println('  flow stream --symbol NVDA [--side call]            Live options-flow feed (SSE)');
   println('  remote-control [--dir DIR]                          Let Atlas run this computer\'s jobs');
   println('  update-cli                                        Install the newest Atlas CLI');