amaprice 1.0.11 → 1.0.13

package/README.md

@@ -35,6 +35,9 @@ amaprice price "https://www.amazon.de/dp/B0DZ5P7JD6"
 # start tracking with a tier
 amaprice track B0DZ5P7JD6 --tier daily
 
+# subscribe current user to shared catalog product
+amaprice subscribe B0DZ5P7JD6
+
 # show history
 amaprice history B0DZ5P7JD6 --limit 30
 
@@ -58,13 +61,35 @@ Short links from Amazon apps (for example `amzn.eu`, `amzn.to`, `a.co`) are acce
 | `amaprice [url\|asin]` | Shortcut for `amaprice price [url\|asin]` |
 | `amaprice price [url\|asin]` | One-shot lookup and silent history insert |
 | `amaprice track [url\|asin]` | Track product + current price (`--tier`, `--manual-tier`, `--auto-tier`, `--inactive`) |
+| `amaprice subscribe [url\|asin]` | Subscribe current user to shared product catalog entry |
+| `amaprice unsubscribe <url\|asin>` | Disable current user subscription |
+| `amaprice subscriptions` | List user subscriptions with latest known prices |
 | `amaprice history <url\|asin>` | Show history (`--limit N`) |
 | `amaprice list` | List tracked products + latest price |
 | `amaprice sync --limit <n>` | Run background sync for due products |
+| `amaprice background <on\|off\|status>` | Manage true background collector service |
 | `amaprice tier <url\|asin> <hourly\|daily\|weekly>` | Set tier/status (`--auto`, `--manual`, `--activate`, `--deactivate`) |
 
 All commands support `--json`.
 
+## Background Service (Auto)
+
+`track` and `subscribe` automatically ensure a true background collector service is running.
+
+This service:
+- keeps running after terminal close
+- survives shell sessions
+- polls queue jobs every `180s` by default
+- currently uses `launchd` on macOS
+
+Simple control commands:
+
+```bash
+amaprice background status
+amaprice background on
+amaprice background off
+```
+
 ## Currently Supported Store
 
 Amazon domains:
@@ -177,12 +202,18 @@ Environment variables used by the npm package:
 | `SYNC_INTERVAL_MINUTES` | `5` | `src/worker.js` | Worker loop interval |
 | `SYNC_LIMIT` | `20` | `src/worker.js`, `amaprice sync --limit` | Max due products per run |
 | `SYNC_RUN_ONCE` | `0` | `src/worker.js` | Set `1` for single run and exit |
+| `AMAPRICE_AUTO_BACKGROUND` | `1` | `track`, `subscribe` | Set `0` to disable auto background startup |
+| `COLLECTOR_POLL_SECONDS` | `180` | background collector service | Queue poll interval |
+| `COLLECTOR_LIMIT` | `10` | background collector service | Max claimed jobs per poll |
 | `VISION_FALLBACK_ENABLED` | `0` | `src/extractors/pipeline.js` | Enable screenshot + vision fallback when HTML/JSON extraction fails |
 | `OPENROUTER_API_KEY` | none | `src/extractors/vision.js` | Preferred vision provider key |
 | `VISION_MODEL` | `google/gemini-3-flash-preview` | `src/extractors/vision.js` | OpenRouter model ID for vision extraction |
 | `VISION_PROVIDER` | auto | `src/extractors/vision.js` | Optional force value: `openrouter` or `openai` |
 | `OPENROUTER_HTTP_REFERER` | none | `src/extractors/vision.js` | Optional OpenRouter attribution header |
 | `OPENROUTER_TITLE` | none | `src/extractors/vision.js` | Optional OpenRouter attribution header |
+| `VISION_GUARDRAIL_ENABLED` | `1` | `src/extractors/pipeline.js` | Reject suspicious vision outputs before DB writes |
+| `VISION_GUARDRAIL_MIN_CONFIDENCE` | `0.92` | `src/extractors/pipeline.js` | Minimum confidence required for vision price acceptance |
+| `VISION_GUARDRAIL_MAX_REL_DELTA` | `0.5` | `src/extractors/pipeline.js` | Max relative delta vs last known price before rejecting vision price |
 | `OPENAI_API_KEY` | none | `src/extractors/vision.js` | Legacy fallback if `OPENROUTER_API_KEY` is unset |
 
 For production background workers, prefer the Supabase **service role key**.
@@ -202,6 +233,9 @@ Steps:
    - `VISION_FALLBACK_ENABLED=1`
    - `OPENROUTER_API_KEY=<your-openrouter-key>`
    - `VISION_MODEL=google/gemini-3-flash-preview`
+   - `VISION_GUARDRAIL_ENABLED=1`
+   - `VISION_GUARDRAIL_MIN_CONFIDENCE=0.92`
+   - `VISION_GUARDRAIL_MAX_REL_DELTA=0.5`
 4. Ensure builder is Dockerfile (root `Dockerfile`).
 5. Deploy.
 6. Confirm logs show `[worker] processed=...`.

package/bin/cli.js

@@ -12,6 +12,7 @@ const KNOWN_COMMANDS = new Set([
   'subscribe',
   'unsubscribe',
   'subscriptions',
+  'background',
   'collector',
   'help',
 ]);
@@ -40,6 +41,7 @@ require('../src/commands/tier')(program);
 require('../src/commands/subscribe')(program);
 require('../src/commands/unsubscribe')(program);
 require('../src/commands/subscriptions')(program);
+require('../src/commands/background')(program);
 require('../src/commands/collector')(program);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amaprice",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "CLI tool to scrape and track Amazon product prices",
   "main": "src/scraper.js",
   "type": "commonjs",

package/src/background/service.js

@@ -0,0 +1,505 @@
+const fs = require('fs/promises');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const { getUserId } = require('../user-context');
+const { readCollectorState, writeCollectorState, getStateDir } = require('../collector/state');
+const { upsertCollector, heartbeatCollector, getCollectorById } = require('../db');
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_COLLECTOR_LIMIT = 10;
+const DEFAULT_POLL_SECONDS = 180;
+const MIN_POLL_SECONDS = 30;
+const MAX_POLL_SECONDS = 3600;
+
+function sanitizeLabelPart(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'user';
+}
+
+function resolveCollectorLimit(value = null) {
+  const parsed = Number(value ?? process.env.COLLECTOR_LIMIT);
+  if (!Number.isFinite(parsed)) return DEFAULT_COLLECTOR_LIMIT;
+  return Math.min(100, Math.max(1, Math.round(parsed)));
+}
+
+function resolvePollSeconds(value = null) {
+  const parsed = Number(value ?? process.env.COLLECTOR_POLL_SECONDS);
+  if (!Number.isFinite(parsed)) return DEFAULT_POLL_SECONDS;
+  return Math.min(MAX_POLL_SECONDS, Math.max(MIN_POLL_SECONDS, Math.round(parsed)));
+}
+
+function getDefaultCollectorName() {
+  return `${os.hostname()}-collector`;
+}
+
+function getDaemonEntryPath() {
+  return path.join(__dirname, '../collector/daemon-entry.js');
+}
+
+function getLaunchdLabel(userId) {
+  return `sh.amaprice.collector.${sanitizeLabelPart(userId)}`;
+}
+
+function getLaunchdPlistPath(label) {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+}
+
+function getDaemonLogPath() {
+  return path.join(getStateDir(), 'collector-daemon.log');
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function renderLaunchdPlist({
+  label,
+  programArguments,
+  stdoutPath,
+  stderrPath,
+  environment = {},
+}) {
+  const argsXml = (programArguments || [])
+    .map((arg) => `      <string>${xmlEscape(arg)}</string>`)
+    .join('\n');
+
+  const envRows = Object.entries(environment || {})
+    .filter(([, value]) => value != null && String(value).trim() !== '')
+    .map(([key, value]) => (
+      `      <key>${xmlEscape(key)}</key>\n      <string>${xmlEscape(value)}</string>`
+    ))
+    .join('\n');
+
+  const envXml = envRows
+    ? `\n    <key>EnvironmentVariables</key>\n    <dict>\n${envRows}\n    </dict>`
+    : '';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argsXml}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${xmlEscape(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(stderrPath)}</string>${envXml}
+  </dict>
+</plist>
+`;
+}
+
+function isLaunchdSupported(platform = process.platform) {
+  return platform === 'darwin';
+}
+
+function getLaunchdDomain() {
+  if (typeof process.getuid !== 'function') {
+    throw new Error('launchd requires a POSIX uid');
+  }
+  return `gui/${process.getuid()}`;
+}
+
+function buildServiceTarget(label) {
+  return `${getLaunchdDomain()}/${label}`;
+}
+
+async function runLaunchctl(args, { allowFailure = false } = {}) {
+  try {
+    const out = await execFileAsync('launchctl', args);
+    return {
+      ok: true,
+      stdout: String(out.stdout || ''),
+      stderr: String(out.stderr || ''),
+    };
+  } catch (err) {
+    if (allowFailure) {
+      return {
+        ok: false,
+        stdout: String(err.stdout || ''),
+        stderr: String(err.stderr || ''),
+        error: err,
+      };
+    }
+    const stderr = String(err.stderr || err.message || '').trim();
+    throw new Error(`launchctl ${args.join(' ')} failed: ${stderr || 'unknown error'}`);
+  }
+}
+
+function isAlreadyLoadedError(result) {
+  const text = `${result?.stderr || ''}\n${result?.stdout || ''}`.toLowerCase();
+  return text.includes('already loaded') || text.includes('service already loaded');
+}
+
+function pickDaemonEnvironment(userId) {
+  const passthrough = [
+    'SUPABASE_URL',
+    'SUPABASE_KEY',
+    'SUPABASE_ANON_KEY',
+    'ORCHESTRATOR_ENABLED',
+    'VISION_FALLBACK_ENABLED',
+    'OPENROUTER_API_KEY',
+    'VISION_MODEL',
+    'VISION_PROVIDER',
+    'OPENROUTER_HTTP_REFERER',
+    'OPENROUTER_TITLE',
+    'VISION_GUARDRAIL_ENABLED',
+    'VISION_GUARDRAIL_MIN_CONFIDENCE',
+    'VISION_GUARDRAIL_MAX_REL_DELTA',
+    'PATH',
+  ];
+
+  const env = {
+    AMAPRICE_USER_ID: userId,
+  };
+  for (const key of passthrough) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
+async function ensureCollectorEnabled({
+  userId = getUserId(),
+  collectorName = null,
+  status = 'active',
+  capabilities = null,
+} = {}) {
+  const existing = await readCollectorState();
+  const collector = await upsertCollector({
+    collectorId: existing?.collectorId || null,
+    userId,
+    name: collectorName || existing?.name || getDefaultCollectorName(),
+    kind: 'cli',
+    status,
+    capabilities: capabilities || existing?.capabilities || {
+      html_json: true,
+      vision: true,
+      railway_dom: true,
+    },
+    metadata: {
+      platform: process.platform,
+      node: process.version,
+    },
+  });
+
+  const state = {
+    collectorId: collector.id,
+    userId,
+    name: collector.name,
+    status,
+    capabilities: collector.capabilities,
+    enabledAt: existing?.enabledAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    background: {
+      ...(existing?.background || {}),
+    },
+  };
+  const statePath = await writeCollectorState(state);
+  return { collector, state, statePath };
+}
+
+async function getLaunchdServiceStatus({ label }) {
+  const plistPath = getLaunchdPlistPath(label);
+  let installed = true;
+  try {
+    await fs.access(plistPath);
+  } catch {
+    installed = false;
+  }
+
+  if (!installed) {
+    return {
+      backend: 'launchd',
+      label,
+      plistPath,
+      installed: false,
+      loaded: false,
+      running: false,
+    };
+  }
+
+  const print = await runLaunchctl(['print', buildServiceTarget(label)], { allowFailure: true });
+  const output = `${print.stdout}\n${print.stderr}`;
+  const loaded = print.ok;
+  const running = loaded && (/state = running/i.test(output) || /pid = \d+/i.test(output));
+
+  return {
+    backend: 'launchd',
+    label,
+    plistPath,
+    installed: true,
+    loaded,
+    running,
+  };
+}
+
+async function enableLaunchdService({
+  label,
+  pollSeconds,
+  limit,
+  userId,
+}) {
+  const plistPath = getLaunchdPlistPath(label);
+  const logPath = getDaemonLogPath();
+  const daemonEntry = getDaemonEntryPath();
+
+  await fs.mkdir(path.dirname(plistPath), { recursive: true });
+  await fs.mkdir(path.dirname(logPath), { recursive: true });
+
+  const plist = renderLaunchdPlist({
+    label,
+    programArguments: [
+      process.execPath,
+      daemonEntry,
+      '--limit',
+      String(limit),
+      '--poll-seconds',
+      String(pollSeconds),
+    ],
+    stdoutPath: logPath,
+    stderrPath: logPath,
+    environment: pickDaemonEnvironment(userId),
+  });
+  await fs.writeFile(plistPath, plist, 'utf8');
+
+  const bootstrap = await runLaunchctl(['bootstrap', getLaunchdDomain(), plistPath], { allowFailure: true });
+  if (!bootstrap.ok && !isAlreadyLoadedError(bootstrap)) {
+    throw new Error(`Could not bootstrap launchd service: ${bootstrap.stderr || bootstrap.stdout || 'unknown error'}`);
+  }
+
+  await runLaunchctl(['enable', buildServiceTarget(label)], { allowFailure: true });
+  const kick = await runLaunchctl(['kickstart', '-k', buildServiceTarget(label)], { allowFailure: true });
+  if (!kick.ok) {
+    await runLaunchctl(['start', label], { allowFailure: true });
+  }
+
+  return getLaunchdServiceStatus({ label });
+}
+
+async function disableLaunchdService({ label }) {
+  const plistPath = getLaunchdPlistPath(label);
+  await runLaunchctl(['bootout', buildServiceTarget(label)], { allowFailure: true });
+  await runLaunchctl(['disable', buildServiceTarget(label)], { allowFailure: true });
+  try {
+    await fs.unlink(plistPath);
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  return getLaunchdServiceStatus({ label });
+}
+
+async function ensureBackgroundOn({
+  userId = getUserId(),
+  collectorName = null,
+  pollSeconds = null,
+  limit = null,
+} = {}) {
+  if (!isLaunchdSupported()) {
+    return {
+      supported: false,
+      running: false,
+      reason: `unsupported_platform:${process.platform}`,
+    };
+  }
+
+  const safePollSeconds = resolvePollSeconds(pollSeconds);
+  const safeLimit = resolveCollectorLimit(limit);
+  const label = getLaunchdLabel(userId);
+  const { collector, statePath } = await ensureCollectorEnabled({
+    userId,
+    collectorName,
+    status: 'active',
+  });
+
+  const service = await enableLaunchdService({
+    label,
+    pollSeconds: safePollSeconds,
+    limit: safeLimit,
+    userId,
+  });
+
+  await heartbeatCollector({
+    collectorId: collector.id,
+    status: 'active',
+  }).catch(() => {});
+
+  const local = await readCollectorState();
+  await writeCollectorState({
+    ...(local || {}),
+    collectorId: collector.id,
+    userId,
+    name: collector.name,
+    status: 'active',
+    background: {
+      enabled: true,
+      backend: 'launchd',
+      label,
+      pollSeconds: safePollSeconds,
+      limit: safeLimit,
+      updatedAt: new Date().toISOString(),
+    },
+    updatedAt: new Date().toISOString(),
+  });
+
+  return {
+    supported: true,
+    running: service.running,
+    service,
+    statePath,
+    collectorId: collector.id,
+    pollSeconds: safePollSeconds,
+    limit: safeLimit,
+  };
+}
+
+async function ensureBackgroundOff({
+  userId = getUserId(),
+} = {}) {
+  const state = await readCollectorState();
+  const label = state?.background?.label || getLaunchdLabel(userId);
+
+  let service = {
+    backend: 'launchd',
+    label,
+    installed: false,
+    loaded: false,
+    running: false,
+  };
+
+  if (isLaunchdSupported()) {
+    service = await disableLaunchdService({ label });
+  }
+
+  if (state?.collectorId) {
+    await heartbeatCollector({
+      collectorId: state.collectorId,
+      status: 'paused',
+    }).catch(() => {});
+  }
+
+  if (state) {
+    await writeCollectorState({
+      ...state,
+      status: 'paused',
+      background: {
+        ...(state.background || {}),
+        enabled: false,
+        backend: 'launchd',
+        label,
+        updatedAt: new Date().toISOString(),
+      },
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  return {
+    supported: isLaunchdSupported(),
+    running: false,
+    service,
+  };
+}
+
+async function getBackgroundStatus({
+  userId = getUserId(),
+} = {}) {
+  const state = await readCollectorState();
+  const remote = state?.collectorId
+    ? await getCollectorById(state.collectorId).catch(() => null)
+    : null;
+  const label = state?.background?.label || getLaunchdLabel(userId);
+
+  const service = isLaunchdSupported()
+    ? await getLaunchdServiceStatus({ label })
+    : {
+      backend: null,
+      label,
+      installed: false,
+      loaded: false,
+      running: false,
+    };
+
+  return {
+    supported: isLaunchdSupported(),
+    userId,
+    local: state,
+    remote,
+    service,
+  };
+}
+
+function isAutoBackgroundEnabled() {
+  return process.env.AMAPRICE_AUTO_BACKGROUND !== '0';
+}
+
+async function maybeEnsureBackgroundOn({
+  userId = getUserId(),
+} = {}) {
+  if (!isAutoBackgroundEnabled()) {
+    return {
+      attempted: false,
+      running: false,
+      reason: 'disabled_by_env',
+    };
+  }
+
+  try {
+    const report = await ensureBackgroundOn({ userId });
+    return {
+      attempted: true,
+      ...report,
+    };
+  } catch (err) {
+    return {
+      attempted: true,
+      running: false,
+      error: err.message,
+    };
+  }
+}
+
+module.exports = {
+  DEFAULT_COLLECTOR_LIMIT,
+  DEFAULT_POLL_SECONDS,
+  MIN_POLL_SECONDS,
+  MAX_POLL_SECONDS,
+  ensureBackgroundOn,
+  ensureBackgroundOff,
+  getBackgroundStatus,
+  maybeEnsureBackgroundOn,
+  resolveCollectorLimit,
+  resolvePollSeconds,
+};
+
+module.exports.__test = {
+  sanitizeLabelPart,
+  resolveCollectorLimit,
+  resolvePollSeconds,
+  getLaunchdLabel,
+  getLaunchdPlistPath,
+  renderLaunchdPlist,
+  isLaunchdSupported,
+};

package/src/collector/client.js

@@ -14,7 +14,7 @@ async function ensureCollectorState() {
   return state;
 }
 
-async function runCollectorOnce({ limit = 5 } = {}) {
+async function runCollectorOnce({ limit = 10 } = {}) {
   const state = await ensureCollectorState();
   await heartbeatCollector({
     collectorId: state.collectorId,
@@ -42,8 +42,8 @@ async function runCollectorOnce({ limit = 5 } = {}) {
   });
 }
 
-async function runCollectorLoop({ limit = 5, pollSeconds = 20 } = {}) {
-  const safePollMs = Math.max(5, Number(pollSeconds) || 20) * 1000;
+async function runCollectorLoop({ limit = 10, pollSeconds = 180 } = {}) {
+  const safePollMs = Math.max(30, Number(pollSeconds) || 180) * 1000;
 
   while (true) {
     const started = Date.now();

package/src/collector/daemon-entry.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { runCollectorLoop } = require('./client');
+
+function parseArg(name, fallback) {
+  const idx = process.argv.indexOf(name);
+  if (idx === -1) return fallback;
+  const value = Number(process.argv[idx + 1]);
+  if (!Number.isFinite(value)) return fallback;
+  return value;
+}
+
+async function main() {
+  const limit = Math.max(1, Math.round(parseArg('--limit', Number(process.env.COLLECTOR_LIMIT) || 10)));
+  const pollSeconds = Math.max(30, Math.round(parseArg('--poll-seconds', Number(process.env.COLLECTOR_POLL_SECONDS) || 180)));
+  await runCollectorLoop({ limit, pollSeconds });
+}
+
+main().catch((err) => {
+  console.error(`[collector-daemon] fatal=${err.message}`);
+  process.exit(1);
+});

package/src/collector/state.js

@@ -43,6 +43,7 @@ async function clearCollectorState() {
 }
 
 module.exports = {
+  getStateDir,
   getCollectorStatePath,
   readCollectorState,
   writeCollectorState,

package/src/commands/background.js

@@ -0,0 +1,97 @@
+const { getUserId } = require('../user-context');
+const {
+  ensureBackgroundOn,
+  ensureBackgroundOff,
+  getBackgroundStatus,
+  resolveCollectorLimit,
+  resolvePollSeconds,
+} = require('../background/service');
+
+module.exports = function (program) {
+  program
+    .command('background <action>')
+    .description('Manage automatic background collector service (on|off|status)')
+    .option('--poll-seconds <n>', 'Polling interval in seconds (default: 180)')
+    .option('--limit <n>', 'Max jobs per poll (default: 10)')
+    .option('--json', 'Output as JSON')
+    .action(async (action, opts) => {
+      const normalizedAction = String(action || '').trim().toLowerCase();
+      const userId = getUserId();
+
+      try {
+        if (normalizedAction === 'on') {
+          const report = await ensureBackgroundOn({
+            userId,
+            pollSeconds: opts.pollSeconds,
+            limit: opts.limit,
+          });
+
+          if (opts.json) {
+            console.log(JSON.stringify(report));
+            return;
+          }
+
+          if (!report.supported) {
+            console.log(`Background service unsupported on platform: ${process.platform}`);
+            return;
+          }
+
+          const pollSeconds = resolvePollSeconds(opts.pollSeconds);
+          const limit = resolveCollectorLimit(opts.limit);
+          console.log(`Background collector ON (poll=${pollSeconds}s limit=${limit})`);
+          return;
+        }
+
+        if (normalizedAction === 'off') {
+          const report = await ensureBackgroundOff({ userId });
+
+          if (opts.json) {
+            console.log(JSON.stringify(report));
+            return;
+          }
+
+          if (!report.supported) {
+            console.log(`Background service unsupported on platform: ${process.platform}`);
+            return;
+          }
+
+          console.log('Background collector OFF');
+          return;
+        }
+
+        if (normalizedAction === 'status') {
+          const report = await getBackgroundStatus({ userId });
+          if (opts.json) {
+            console.log(JSON.stringify(report));
+            return;
+          }
+
+          if (!report.supported) {
+            console.log(`Background service unsupported on platform: ${process.platform}`);
+            return;
+          }
+
+          console.log(`Background collector: ${report.service.running ? 'running' : 'stopped'}`);
+          if (report.local?.background?.pollSeconds) {
+            console.log(`Poll interval:       ${report.local.background.pollSeconds}s`);
+          }
+          if (report.local?.background?.limit) {
+            console.log(`Poll limit:          ${report.local.background.limit}`);
+          }
+          if (report.local?.collectorId) {
+            console.log(`Collector ID:        ${report.local.collectorId}`);
+          }
+          if (report.remote?.last_seen_at) {
+            console.log(`Last heartbeat:      ${report.remote.last_seen_at}`);
+          }
+          return;
+        }
+
+        console.error('Unknown background action. Use: on, off, status.');
+        process.exit(1);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+};

package/src/commands/collector.js

@@ -23,16 +23,16 @@ function getDefaultCollectorName() {
 module.exports = function (program) {
   program
     .command('collector <action>')
-    .description('Manage local collector daemon (enable|disable|status|pause|resume|run-once|start)')
+    .description('Manage local collector process (advanced/debug)')
     .option('--name <name>', 'Collector name override')
-    .option('--limit <n>', 'Max jobs per loop/once run', '5')
-    .option('--poll-seconds <n>', 'Polling interval for start loop', '20')
+    .option('--limit <n>', 'Max jobs per loop/once run', '10')
+    .option('--poll-seconds <n>', 'Polling interval for start loop', '180')
     .option('--json', 'Output as JSON')
     .action(async (action, opts) => {
       const normalizedAction = String(action || '').trim().toLowerCase();
       const userId = getUserId();
-      const limit = Math.max(1, Number(opts.limit) || 5);
-      const pollSeconds = Math.max(5, Number(opts.pollSeconds) || 20);
+      const limit = Math.max(1, Number(opts.limit) || 10);
+      const pollSeconds = Math.max(30, Number(opts.pollSeconds) || 180);
 
       try {
         if (normalizedAction === 'enable') {

package/src/commands/subscribe.js

@@ -10,6 +10,7 @@ const {
   upsertUserSubscription,
 } = require('../db');
 const { getUserId } = require('../user-context');
+const { maybeEnsureBackgroundOn } = require('../background/service');
 const { normalizeTier, computeNextScrapeAt } = require('../tiering');
 
 module.exports = function (program) {
@@ -95,6 +96,7 @@ module.exports = function (program) {
           tierPref: selectedTier,
           isActive: true,
         });
+        const background = await maybeEnsureBackgroundOn({ userId });
 
         if (opts.json) {
           console.log(JSON.stringify({
@@ -111,6 +113,7 @@ module.exports = function (program) {
             },
             initialPrice: initial?.price?.numeric || null,
             initialCurrency: initial?.price?.currency || null,
+            background,
           }));
           return;
         }
@@ -118,6 +121,11 @@ module.exports = function (program) {
         console.log(`Subscribed: ${product.asin} (${product.title})`);
         console.log(`User:       ${userId}`);
         console.log(`Tier pref:  ${subscription.tier_pref || 'default'}`);
+        if (background.running) {
+          console.log(`Background: running (${background.pollSeconds || 180}s poll)`);
+        } else if (background.attempted && background.error) {
+          console.log(`Background: setup failed (${background.error})`);
+        }
       } catch (err) {
         console.error(`Error: ${err.message}`);
         process.exit(1);

package/src/commands/track.js

@@ -9,6 +9,7 @@ const {
   upsertProductLatestPrice,
 } = require('../db');
 const { getUserId } = require('../user-context');
+const { maybeEnsureBackgroundOn } = require('../background/service');
 const { normalizeTier, computeNextScrapeAt } = require('../tiering');
 
 module.exports = function (program) {
@@ -74,6 +75,7 @@ module.exports = function (program) {
         const nextTier = normalizeTier(product.tier, selectedTier || 'daily');
         const userId = getUserId();
         let subscription = null;
+        const background = await maybeEnsureBackgroundOn({ userId });
         try {
           await updateProductById(product.id, {
             last_price: result.price.numeric,
@@ -108,12 +110,18 @@ module.exports = function (program) {
             active: opts.inactive ? false : (product.is_active ?? true),
             userId,
             subscribed: Boolean(subscription),
+            background,
           }));
         } else {
           console.log(`Tracking: ${result.title}`);
           console.log(`ASIN:     ${result.asin}`);
           console.log(`Price:    ${result.priceRaw}`);
           console.log(`Tier:     ${nextTier}`);
+          if (background.running) {
+            console.log(`Background collector: running (${background.pollSeconds || 180}s poll)`);
+          } else if (background.attempted && background.error) {
+            console.log(`Background collector: setup failed (${background.error})`);
+          }
           console.log(`Saved to Supabase.`);
         }
       } catch (err) {

package/src/extractors/pipeline.js

@@ -106,14 +106,81 @@ function normalizeScraperResult(result, method) {
   };
 }
 
+function toFiniteNumber(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function readFloatEnv(name, fallback, { min = null, max = null } = {}) {
+  const raw = process.env[name];
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  if (min != null && parsed < min) return min;
+  if (max != null && parsed > max) return max;
+  return parsed;
+}
+
+function isVisionGuardrailEnabled() {
+  return process.env.VISION_GUARDRAIL_ENABLED !== '0';
+}
+
+function getVisionMinConfidence() {
+  return readFloatEnv('VISION_GUARDRAIL_MIN_CONFIDENCE', 0.92, { min: 0, max: 1 });
+}
+
+function getVisionMaxRelativeDelta() {
+  return readFloatEnv('VISION_GUARDRAIL_MAX_REL_DELTA', 0.5, { min: 0, max: 10 });
+}
+
+function evaluateVisionGuardrails(result, {
+  baselinePrice = null,
+  enabled = isVisionGuardrailEnabled(),
+  minConfidence = getVisionMinConfidence(),
+  maxRelativeDelta = getVisionMaxRelativeDelta(),
+} = {}) {
+  if (!enabled) {
+    return { accepted: true, reason: null };
+  }
+
+  if (!result || result.method !== 'vision' || !result.price) {
+    return { accepted: true, reason: null };
+  }
+
+  const confidence = toFiniteNumber(result.confidence) || 0;
+  if (confidence < minConfidence) {
+    return {
+      accepted: false,
+      reason: `low_confidence:${confidence.toFixed(3)}<${Number(minConfidence).toFixed(3)}`,
+    };
+  }
+
+  const extracted = toFiniteNumber(result.price?.numeric);
+  const baseline = toFiniteNumber(baselinePrice);
+  if (extracted == null || baseline == null || baseline <= 0) {
+    return { accepted: true, reason: null };
+  }
+
+  const relativeDelta = Math.abs(extracted - baseline) / baseline;
+  if (relativeDelta > maxRelativeDelta) {
+    return {
+      accepted: false,
+      reason: `relative_delta:${relativeDelta.toFixed(3)}>${Number(maxRelativeDelta).toFixed(3)}`,
+    };
+  }
+
+  return { accepted: true, reason: null };
+}
+
 async function runCollectionPipeline({
   url,
   domain = null,
   allowVision = true,
   allowRailwayDomFallback = true,
+  baselinePrice = null,
 }) {
   const effectiveDomain = domain || extractDomain(url);
   const fallbackCurrency = fallbackCurrencyForDomain(effectiveDomain);
+  let rejectedVisionResult = null;
 
   const htmlJsonResult = normalizeScraperResult(
     await runHtmlJsonExtraction(url, { fallbackCurrency }),
@@ -139,9 +206,30 @@ async function runCollectionPipeline({
         finalUrl: shot.finalUrl,
       }, 'vision');
 
-      if (normalizedVision.price || normalizedVision.blockedSignal) {
+      if (normalizedVision.blockedSignal) {
         return normalizedVision;
       }
+
+      if (normalizedVision.price) {
+        const guardrail = evaluateVisionGuardrails(normalizedVision, { baselinePrice });
+        if (guardrail.accepted) {
+          return normalizedVision;
+        }
+
+        rejectedVisionResult = {
+          ...normalizedVision,
+          status: 'no_price',
+          price: null,
+          blockedSignal: false,
+          blockedReason: null,
+          debug: {
+            ...(normalizedVision.debug || {}),
+            guardrail: 'rejected',
+            guardrailReason: guardrail.reason,
+            baselinePrice: toFiniteNumber(baselinePrice),
+          },
+        };
+      }
     } catch (err) {
       // Continue to DOM fallback.
     }
@@ -152,7 +240,7 @@ async function runCollectionPipeline({
     return normalizeScraperResult(domResult, 'railway_dom');
   }
 
-  return htmlJsonResult;
+  return rejectedVisionResult || htmlJsonResult;
 }
 
 module.exports = {
@@ -163,4 +251,7 @@ module.exports = {
 module.exports.__test = {
   fallbackCurrencyForDomain,
   normalizeScraperResult,
+  evaluateVisionGuardrails,
+  getVisionMinConfidence,
+  getVisionMaxRelativeDelta,
 };

package/src/extractors/vision.js

@@ -185,6 +185,19 @@ function isVisionEnabled() {
   return process.env.VISION_FALLBACK_ENABLED === '1';
 }
 
+function buildVisionPrompt() {
+  return [
+    'You extract the final payable price from an Amazon product-detail screenshot.',
+    'Respond with JSON only using exactly keys: price, currency, confidence, is_blocked, reason, raw_text.',
+    'price must be a decimal number (dot separator), or null when uncertain.',
+    'Only use the main buy-box product price for the shown product.',
+    'Ignore list/strike prices, "from" ranges, installment/monthly values, coupons, shipping, used/new offers, bundle prices, and sponsored/related product prices.',
+    'If the page is captcha/challenge/login/cookie-wall and price is not clearly visible, set is_blocked=true and price=null.',
+    'If multiple plausible prices exist, set price=null.',
+    'confidence must be a number between 0 and 1.',
+  ].join(' ');
+}
+
 async function requestOpenRouter({ apiKey, model, prompt, base64 }) {
   const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
@@ -291,12 +304,7 @@ async function extractPriceFromScreenshotBuffer(imageBuffer, {
     };
   }
 
-  const prompt = [
-    'Extract the currently visible final product price from this e-commerce screenshot.',
-    'Respond with JSON only and keys: price, currency, confidence, is_blocked, reason, raw_text.',
-    'Use decimal number for price (example: 79.99).',
-    'If price is not clearly visible, set price=null and confidence<=0.5.',
-  ].join(' ');
+  const prompt = buildVisionPrompt();
 
   const transport = selected.name === 'openrouter'
     ? await requestOpenRouter({
@@ -352,6 +360,7 @@ module.exports = {
 };
 
 module.exports.__test = {
+  buildVisionPrompt,
   extractJsonBlock,
   extractOutputText,
   getProvider,

package/src/orchestrator/runner.js

@@ -94,6 +94,7 @@ async function processClaimedJob(job, {
       domain: job.domain,
       allowVision,
       allowRailwayDomFallback,
+      baselinePrice: job.last_price,
     });
 
     if (!result.price) {