getlull 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# ◆ getlull
+
+**Get paid for the idle seconds you already spend watching your AI coding agent think.**
+
+Lull shows **one** short, clearly-labeled sponsor line in your coding agent's spinner / status
+line during wait states — then it's gone. Between ads, your status line shows your balance ticking
+up live (`⚡ Lull · $0.42 today · $7.11 total`). You keep **70%**. It's open-source, ships signed
+releases, and **never reads your prompts, code, or files**.
+
+```bash
+npx getlull init        # create a device key, approve in the browser, wire into your agent
+lull status             # install state + device id + balance
+lull wallet             # earnings
+lull config country IN  # (optional) see country-targeted sponsors — self-declared, never geolocated
+lull pause              # mute the line
+lull uninstall          # restore your original config exactly
+```
+
+## Why you'd trust it
+
+- **Status-line only.** The client drains the agent's input *without reading it* — zero access to
+  your prompts, files, diffs, or commits. The entire impression payload is
+  `{ deviceId, creativeId, dwellMs, signature }`.
+- **Open-source + signed releases.** Read it, build it, diff it against the signed manifest.
+- **Documented extension points only** — it never patches your editor's bundle.
+- **Earnings can't be forged in your name** — every impression is signed by a per-device Ed25519
+  key that never leaves your machine; abuse is bounded by rate caps, a clearing hold, and review.
+- **Real payouts** — UPI in India (₹400 floor) or USD worldwide via Stripe ($10 floor). No points.
+
+🔗 [getlull.dev](https://getlull.dev) · [How it works](https://getlull.dev/how-it-works/) · [Source](https://github.com/sonusrujan/lull) · [Apache-2.0](../LICENSE)
+
+> **Status: pre-launch.** The client works with **Claude Code** today; Codex and Cursor/VS Code are
+> in progress. Payouts are manual for the first cohort. A product of **NarraTech Pvt Ltd**.

package/bin/lull.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Lull CLI (Plan 1).  Commands: init | status | off | uninstall | wallet
+//   init      -> create device identity, register public key, wire into Claude Code
+//   status    -> show install state + device id + balance
+//   wallet    -> show current earnings
+//   off       -> remove the status line but keep the device identity
+//   uninstall -> remove the status line (identity file stays unless --purge)
+
+import { createDevice, loadDevice, saveToken, purgeDevice } from '../src/identity.mjs';
+import { installStatusLine, uninstallStatusLine, isInstalled, agentStatus, setSpinnerVerbs, clearSpinnerVerbs, SETTINGS } from '../src/config.mjs';
+import { keychainBackend } from '../src/keychain.mjs';
+import { getPrefs, setPref, blockCategory, unblockCategory } from '../src/prefs.mjs';
+import { api } from '../src/api.mjs';
+import { execFile } from 'node:child_process';
+
+const cmd = process.argv[2] || 'help';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function openBrowser(u) {
+  const c = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  execFile(c, [u], () => {});
+}
+
+async function init() {
+  let device = loadDevice();
+  if (!device) { device = createDevice(); console.log(`[lull] created device ${device.deviceId} (key in ${keychainBackend()})`); }
+  else console.log(`[lull] using existing device ${device.deviceId}`);
+
+  // Device-authorization flow: human approves in the browser before any token is issued.
+  try {
+    const start = await api.deviceStart(device.deviceId, device.publicKeyPem);
+    console.log('');
+    console.log('  Approve this device to start earning:');
+    console.log(`    ${start.verification_uri_complete}`);
+    console.log(`    code: ${start.user_code}`);
+    console.log('');
+    openBrowser(start.verification_uri_complete);
+
+    process.stdout.write('  waiting for approval');
+    const deadline = Date.now() + (start.expires_in || 600) * 1000;
+    while (Date.now() < deadline) {
+      await sleep((start.interval || 2) * 1000);
+      const r = await api.devicePoll(start.device_code);
+      if (r.token) {
+        saveToken(device.deviceId, r.token);
+        console.log(`\n[lull] approved. token stored in ${keychainBackend()} (scopes: ${r.scopes.join(', ')})`);
+        break;
+      }
+      process.stdout.write('.');
+    }
+    if (!loadDevice().token) { console.log('\n[lull] not approved in time — re-run: lull init'); return; }
+  } catch (e) {
+    console.log(`\n[lull] WARNING: backend not reachable (${api.base}) — start the server, then re-init.`);
+    return;
+  }
+
+  const r = installStatusLine();
+  console.log(`[lull] wired into agents: ${r.installed.join(', ') || '(none detected)'}`);
+  // Seed the "thinking" spinner with a sponsor line (Claude Code 2.1.23+) so it shows on next start.
+  const sm = getPrefs().spinnerMode;
+  if (sm !== 'off') {
+    try { const { creative } = await api.serve({ deviceId: device.deviceId }); setSpinnerVerbs([`▸ Sponsored · ${creative.text} · getlull.dev`], sm || 'replace'); console.log(`[lull] sponsor line added to the thinking spinner (mode: ${sm}). Disable: lull config spinnerMode off`); } catch {}
+  }
+  console.log(`[lull] originals backed up alongside each config. Revert anytime: lull uninstall`);
+  console.log('[lull] restart your agent(s) to see it.');
+}
+
+async function status() {
+  const device = loadDevice();
+  const p = getPrefs();
+  console.log(`installed:  ${isInstalled() ? 'yes' : 'no'}`);
+  console.log(`device:     ${device ? device.deviceId : '(none — run: lull init)'}`);
+  console.log(`keychain:   ${keychainBackend()}`);
+  console.log(`token:      ${device?.token ? 'present (least-privilege, in keychain)' : 'none'}`);
+  console.log(`backend:    ${api.base}`);
+  console.log(`display:    ${p.enabled ? 'on' : 'paused'} · ${p.adSeconds}s ad / ${p.restSeconds}s rest · cap ${p.maxPerHour}/hr`);
+  console.log(`blocked:    ${p.blockedCategories.length ? p.blockedCategories.join(', ') : '(none — lull block <category>)'}`);
+  console.log('agents:');
+  for (const a of agentStatus()) {
+    const mark = !a.detected ? 'not found' : a.installed ? 'installed' : 'detected (run: lull init)';
+    console.log(`  ${a.installed ? '●' : a.detected ? '○' : '·'} ${a.name.padEnd(12)} ${mark}`);
+  }
+  if (device) await wallet();
+}
+
+function config() {
+  const [, , , key, value] = process.argv;   // lull config <key> <value>
+  if (!key) { console.log('config:'); for (const [k, v] of Object.entries(getPrefs())) console.log(`  ${k} = ${v}`); console.log('\nset with: lull config <key> <value>   (base, adSeconds, restSeconds, maxPerHour, enabled)'); return; }
+  if (value === undefined) { console.log(`${key} = ${getPrefs()[key]}`); return; }
+  const out = setPref(key, value);
+  console.log(`[lull] set ${key} = ${out[key]}`);
+}
+
+async function wallet() {
+  const device = loadDevice();
+  if (!device) return console.log('no device — run: lull init');
+  try {
+    const w = await api.wallet(device.deviceId);
+    console.log(`balance:    $${w.balanceUsd}  (${w.impressionsBillable} billable / ${w.impressionsDropped} dropped)`);
+  } catch { console.log('balance:    (backend unreachable)'); }
+}
+
+function off() { clearSpinnerVerbs(); uninstallStatusLine(); console.log('[lull] status line + spinner removed (device kept). Restart Claude Code.'); }
+function uninstall() {
+  clearSpinnerVerbs();
+  const r = uninstallStatusLine();
+  if (process.argv.includes('--purge')) {
+    const d = loadDevice(); if (d) { purgeDevice(d.deviceId); console.log('[lull] purged device keys from keychain.'); }
+  }
+  console.log(`[lull] uninstalled (${r.restoredFrom ? 'restored backup' : 'removed key'}). Restart Claude Code.`);
+}
+
+function pause() { setPref('enabled', false); console.log('[lull] paused — sponsor line stays quiet (device + install kept). Resume: lull resume'); }
+function resume() { setPref('enabled', true); console.log('[lull] resumed.'); }
+
+const CATEGORIES = ['database', 'observability', 'ai-tools', 'api', 'hiring', 'security', 'cloud', 'devtools'];
+function block() {
+  const cat = process.argv[3];
+  if (!cat) { console.log('your inventory, your veto. block a category so those ads never show:\n  categories: ' + CATEGORIES.join(', ') + '\n  blocked:    ' + (getPrefs().blockedCategories.join(', ') || '(none)') + '\n  usage: lull block <category>'); return; }
+  const out = blockCategory(cat); console.log(`[lull] blocked "${cat}". now hidden: ${out.blockedCategories.join(', ')}`);
+}
+function unblock() { const cat = process.argv[3]; if (!cat) return console.log('usage: lull unblock <category>'); const out = unblockCategory(cat); console.log(`[lull] unblocked "${cat}". blocked: ${out.blockedCategories.join(', ') || '(none)'}`); }
+
+const table = {
+  init, status, wallet, config, pause, resume, block, unblock, off, uninstall,
+  help: () => console.log('usage: lull <init|status|wallet|config|block|unblock|pause|resume|off|uninstall>'),
+};
+(table[cmd] || table.help)();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "getlull",
+  "version": "0.1.0",
+  "description": "Get paid for the idle time you spend watching your AI coding agent think. Open-source, signed, status-line only. You keep 70%.",
+  "type": "module",
+  "bin": {
+    "lull": "bin/lull.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "release-public.pem",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lull": "node bin/lull.mjs"
+  },
+  "keywords": [
+    "ai", "coding-agent", "claude-code", "cursor", "codex", "status-line",
+    "ads", "monetization", "developer-tools", "passive-income"
+  ],
+  "homepage": "https://getlull.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonusrujan/lull.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sonusrujan/lull/issues"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/release-public.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA9ou3jk2hSDKIGAUTLw0/i7NtKrpE4aHz6T/EmlGacPA=
+-----END PUBLIC KEY-----

package/src/adapters.mjs

@@ -0,0 +1,137 @@
+// Lull client — multi-agent adapter layer.
+// The render core (status line + signed beacon) is identical across agents; only the
+// "where do I install the hook" differs. Each adapter knows how to: detect the agent,
+// install the Lull hook (backing up first), uninstall (restoring), and report state.
+//
+// Surfaces: Claude Code (native status line) and Codex CLI (lifecycle hook in hooks.json →
+// terminal render) hook into config files; Cursor / VS Code load a companion status-bar
+// extension. Each degrades to "not detected" rather than touching a tool that isn't there, and
+// only ever adds/removes its OWN entry (backing up first), never clobbering the user's config.
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync, cpSync, rmSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const STATUSLINE = resolve(__dir, 'statusline.mjs');
+// Use the ABSOLUTE node path — Claude Code runs the status-line command with a minimal PATH
+// that may not include Homebrew's bin, so a bare `node` would fail silently (blank status line).
+const CMD = `${process.execPath} ${STATUSLINE}`;
+const CODEX_HOOK = resolve(__dir, 'codex-hook.mjs');         // Codex lifecycle-hook renderer
+const CODEX_CMD = `${process.execPath} ${CODEX_HOOK}`;
+const EXT_SRC = resolve(__dir, '..', '..', 'extension');     // the VS Code/Cursor extension source
+const EXT_FOLDER = 'lull.lull-vscode-0.1.0';                  // <publisher>.<name>-<version>
+
+function readJson(p) { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; }
+}
+function backupOnce(file) {
+  const bak = file + '.lull-backup';
+  if (existsSync(file) && !existsSync(bak)) copyFileSync(file, bak);
+  return bak;
+}
+function restore(file) {
+  const bak = file + '.lull-backup';
+  if (existsSync(bak)) { copyFileSync(bak, file); return { restoredFrom: bak }; }
+  return null;
+}
+
+// ---- Claude Code: native statusLine command ----
+const claude = {
+  id: 'claude-code',
+  name: 'Claude Code',
+  configPath: join(homedir(), '.claude', 'settings.json'),
+  detect() { return existsSync(join(homedir(), '.claude')); },
+  isInstalled() {
+    const s = readJson(this.configPath);
+    return !!(s.statusLine && String(s.statusLine.command || '').includes('statusline.mjs'));
+  },
+  install() {
+    backupOnce(this.configPath);
+    const s = existsSync(this.configPath) ? readJson(this.configPath) : {};
+    s.statusLine = { type: 'command', command: CMD, padding: 0 };
+    writeFileSync(this.configPath, JSON.stringify(s, null, 2));
+    return { agent: this.id, configPath: this.configPath };
+  },
+  uninstall() {
+    const r = restore(this.configPath);
+    if (!r) { const s = readJson(this.configPath); delete s.statusLine; writeFileSync(this.configPath, JSON.stringify(s, null, 2)); }
+    return { agent: this.id, ...(r || { removedKey: true }) };
+  },
+};
+
+// ---- Codex CLI: lifecycle hook via ~/.codex/hooks.json ----
+// Codex has no command-backed status line, but it DOES run lifecycle hooks (PreToolUse, etc.)
+// from ~/.codex/hooks.json (same shape as Claude Code's hooks). We register a PreToolUse hook
+// matching every tool; it runs codex-hook.mjs, which prints the OSC-8 sponsor line to the
+// terminal while the agent works. config.toml is never touched. We only ever add/remove OUR
+// entry, preserving any hooks the user already has.
+const CODEX_MARK = 'codex-hook.mjs';
+const hasOurHook = (h) => (h?.hooks?.PreToolUse || []).some((e) => (e.hooks || []).some((x) => String(x.command || '').includes(CODEX_MARK)));
+const stripOurHook = (h) => {
+  if (!h?.hooks?.PreToolUse) return h;
+  h.hooks.PreToolUse = h.hooks.PreToolUse
+    .map((e) => ({ ...e, hooks: (e.hooks || []).filter((x) => !String(x.command || '').includes(CODEX_MARK)) }))
+    .filter((e) => (e.hooks || []).length);
+  if (!h.hooks.PreToolUse.length) delete h.hooks.PreToolUse;
+  if (h.hooks && !Object.keys(h.hooks).length) delete h.hooks;
+  return h;
+};
+const codex = {
+  id: 'codex',
+  name: 'Codex CLI',
+  configPath: join(homedir(), '.codex', 'hooks.json'),
+  detect() { return existsSync(join(homedir(), '.codex')); },
+  isInstalled() { return hasOurHook(readJson(this.configPath)); },
+  install() {
+    backupOnce(this.configPath);
+    const h = existsSync(this.configPath) ? readJson(this.configPath) : {};
+    stripOurHook(h);                                   // idempotent: drop any stale Lull entry first
+    h.hooks = h.hooks || {};
+    h.hooks.PreToolUse = h.hooks.PreToolUse || [];
+    h.hooks.PreToolUse.push({ matcher: '.*', hooks: [{ type: 'command', command: CODEX_CMD, timeout: 5, statusMessage: 'Lull' }] });
+    writeFileSync(this.configPath, JSON.stringify(h, null, 2));
+    return { agent: this.id, configPath: this.configPath, note: 'codex hook installed — verify render in a live Codex session' };
+  },
+  uninstall() {
+    const r = restore(this.configPath);
+    if (r) return { agent: this.id, ...r };
+    if (existsSync(this.configPath)) {
+      const h = stripOurHook(readJson(this.configPath));
+      if (!Object.keys(h).length) { rmSync(this.configPath, { force: true }); return { agent: this.id, removedFile: true }; }
+      writeFileSync(this.configPath, JSON.stringify(h, null, 2));
+    }
+    return { agent: this.id, removedKey: true };
+  },
+};
+
+// ---- Cursor / VS Code: status bar via a companion extension ----
+// These agents expose the status bar to *extensions*, not a config command. The Lull hook is a
+// tiny extension (../extension) calling the same /serve + signed-beacon API. We "install" it by
+// copying it into the editor's extensions dir (loaded on next reload). Status-bar only.
+const cursor = extensionAdapter('cursor', 'Cursor', join(homedir(), '.cursor', 'extensions'));
+const vscode = extensionAdapter('vscode', 'VS Code', join(homedir(), '.vscode', 'extensions'));
+
+function extensionAdapter(id, name, extDir) {
+  const target = join(extDir, EXT_FOLDER);
+  return {
+    id, name, configPath: target,
+    detect() { return existsSync(extDir) || existsSync(dirname(extDir)); },
+    isInstalled() { return existsSync(join(target, 'extension.js')); },
+    install() {
+      if (!existsSync(EXT_SRC)) return { agent: id, error: 'extension source missing' };
+      mkdirSync(extDir, { recursive: true });
+      cpSync(EXT_SRC, target, { recursive: true });
+      return { agent: id, installedTo: target, note: `reload ${name} to activate` };
+    },
+    uninstall() {
+      if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+      return { agent: id, removed: target };
+    },
+  };
+}
+
+export const ADAPTERS = [claude, codex, cursor, vscode];
+
+export function detectAgents() { return ADAPTERS.filter((a) => a.detect()); }
+export function getAdapter(id) { return ADAPTERS.find((a) => a.id === id); }

package/src/api.mjs

@@ -0,0 +1,41 @@
+// Lull client — backend API helper (zero deps, fast timeouts so the status line never hangs).
+// Reads the base URL from prefs (env > config.json > default) and speaks http or https
+// automatically, so the same client works against localhost and a deployed https backend.
+
+import http from 'node:http';
+import https from 'node:https';
+import { getBase } from './prefs.mjs';
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, getBase());
+    const mod = url.protocol === 'https:' ? https : http;
+    const data = body ? JSON.stringify(body) : null;
+    const headers = { 'content-type': 'application/json' };
+    if (data) headers['content-length'] = Buffer.byteLength(data);
+    const req = mod.request(url, { method, timeout: 800, headers }, (res) => {
+      let d = ''; res.on('data', (c) => (d += c));
+      res.on('end', () => { try { resolve(JSON.parse(d || '{}')); } catch (e) { reject(e); } });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+export const api = {
+  get base() { return getBase(); },
+  deviceStart: (deviceId, publicKeyPem) => call('POST', '/v1/auth/device/start', { deviceId, publicKeyPem }),
+  devicePoll: (device_code) => call('POST', '/v1/auth/device/poll', { device_code }),
+  serve: (opts = {}) => {
+    const q = new URLSearchParams();
+    if (opts.deviceId) q.set('device', opts.deviceId);
+    if (opts.blocked && opts.blocked.length) q.set('block', opts.blocked.join(','));
+    if (opts.country) q.set('country', String(opts.country).toUpperCase());   // self-declared, optional
+    const s = q.toString();
+    return call('GET', '/v1/serve' + (s ? '?' + s : ''));
+  },
+  reportImpression: (payload, signature) => call('POST', '/v1/impressions', { payload, signature }),
+  wallet: (deviceId) => call('GET', `/v1/wallet?deviceId=${encodeURIComponent(deviceId)}`),
+};

package/src/codex-hook.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Lull hook for Codex CLI. Registered in ~/.codex/hooks.json on PreToolUse, so Codex runs it
+// while the agent is actively working. Codex has no command-backed status line, so instead of a
+// footer we print the sponsor line straight to the CONTROLLING TERMINAL (/dev/tty) with an OSC-8
+// hyperlink (clickable in iTerm2/Kitty/WezTerm; plain text elsewhere).
+//
+// Why /dev/tty and not stdout: Codex captures a hook's stdout for its hook protocol, so writing
+// the ad there would corrupt it. We write to /dev/tty and leave stdout empty + exit 0 cleanly.
+// Privacy: the hook event JSON on stdin is drained and never inspected.
+
+import { loadDevice } from './identity.mjs';
+import { getPrefs } from './prefs.mjs';
+import { produce } from './render-core.mjs';
+import { openSync, writeSync, closeSync } from 'node:fs';
+
+function drainStdin() {
+  return new Promise((resolve) => {
+    let n = 0;
+    process.stdin.on('data', (c) => (n += c.length));
+    process.stdin.on('end', () => resolve(n));
+    setTimeout(() => resolve(n), 40);
+  });
+}
+
+// Print straight to the user's terminal, bypassing stdout. Returns false if there's no tty
+// (e.g. piped/headless) so we degrade silently instead of throwing.
+export function writeTty(line) {
+  let fd;
+  try { fd = openSync('/dev/tty', 'w'); writeSync(fd, line + '\n'); return true; }
+  catch { return false; }
+  finally { if (fd !== undefined) try { closeSync(fd); } catch {} }
+}
+
+async function main() {
+  await drainStdin();
+  const device = loadDevice();
+  if (!device) return;                                   // not signed in → clean no-op
+  const line = await produce(device, getPrefs(), { setVerbs: false });
+  if (line) writeTty(line);                              // empty during the quiet phase → show nothing
+}
+
+main();

package/src/config.mjs

@@ -0,0 +1,64 @@
+// Lull client — agent integration (multi-agent via adapters.mjs).
+// Installs/uninstalls the Lull hook across every detected coding agent. Backward-compatible
+// function names are kept for the CLI.
+
+import { detectAgents, ADAPTERS, getAdapter } from './adapters.mjs';
+import { readFileSync, writeFileSync, existsSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Back-compat alias used elsewhere (Claude Code's settings path).
+const SETTINGS = join(homedir(), '.claude', 'settings.json');
+const BACKUP = SETTINGS + '.lull-backup';
+
+function readSettings() { try { return JSON.parse(readFileSync(SETTINGS, 'utf8')); } catch { return {}; } }
+// Atomic write: stage to a temp file then rename, so the agent never reads a partial settings.json.
+function writeSettings(s) {
+  const tmp = `${SETTINGS}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(s, null, 2));
+  renameSync(tmp, SETTINGS);
+}
+
+// Sponsored "thinking" verbs — Claude Code 2.1.23+ `spinnerVerbs` replaces/append the spinner
+// text. This puts the sponsor line where the "Crunching…/Cooking…" text shows. The statusLine
+// command keeps recording the precise signed impression; the spinner is display-only.
+export function setSpinnerVerbs(verbs, mode = 'replace') {
+  if (!existsSync(SETTINGS) || !verbs?.length) return;
+  const s = readSettings();
+  s.spinnerVerbs = { mode, verbs };
+  writeSettings(s);
+}
+export function clearSpinnerVerbs() {
+  if (!existsSync(SETTINGS)) return;
+  const s = readSettings();
+  if (s.spinnerVerbs) { delete s.spinnerVerbs; writeSettings(s); }
+}
+
+// Install into all detected agents; returns per-agent results.
+export function installStatusLine() {
+  const agents = detectAgents();
+  const results = agents.map((a) => a.install());
+  const primary = agents.find((a) => a.id === 'claude-code') || agents[0];
+  return {
+    settingsPath: primary ? primary.configPath : SETTINGS,
+    backupPath: BACKUP,
+    agents: results,
+    installed: agents.map((a) => a.id),
+  };
+}
+
+export function uninstallStatusLine() {
+  const results = detectAgents().map((a) => a.uninstall());
+  const restored = results.some((r) => r.restoredFrom);
+  return { restoredFrom: restored ? BACKUP : null, agents: results };
+}
+
+export function isInstalled() {
+  return detectAgents().some((a) => a.isInstalled());
+}
+
+export function agentStatus() {
+  return ADAPTERS.map((a) => ({ id: a.id, name: a.name, detected: a.detect(), installed: a.detect() && a.isInstalled() }));
+}
+
+export { SETTINGS, BACKUP };

package/src/identity.mjs

@@ -0,0 +1,90 @@
+// Lull client — device identity.
+// Each install owns an Ed25519 keypair. The PRIVATE key never leaves the machine and is used
+// to SIGN impression beacons; the server only ever sees the PUBLIC key. This makes earnings
+// unspoofable: you can't forge impressions for a device without its private key.
+//
+// Storage: the PRIVATE key + token live in the OS keychain (macOS Keychain / Linux libsecret),
+// falling back to a 0600 file in ~/.lull on headless/Windows/locked-keyring systems — see
+// keychain.mjs. Only NON-secret metadata (deviceId, public key) is written to ~/.lull/device.json.
+
+import { generateKeyPairSync, sign as edSign, createPrivateKey, createPublicKey } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setSecret, getSecret, deleteSecret, keychainBackend } from './keychain.mjs';
+
+const DIR = join(homedir(), '.lull');
+const DEVICE_FILE = join(DIR, 'device.json');   // NON-secret metadata only (id + public key)
+
+function ensureDir() {
+  if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true, mode: 0o700 });
+}
+
+// Create a new device identity (called once at `init`).
+// Secrets (private key) -> OS keychain. Metadata (id, public key, token state) -> device.json.
+export function createDevice() {
+  ensureDir();
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const priv = privateKey.export({ type: 'pkcs8', format: 'pem' });
+  const pub = publicKey.export({ type: 'spki', format: 'pem' });
+  const deviceId = 'dev_' + cryptoRandomId();
+
+  setSecret(`${deviceId}:privkey`, priv);   // -> keychain
+  const meta = { deviceId, publicKeyPem: pub, hasToken: false, createdAt: nowIso(),
+    keychain: keychainBackend() };
+  writeFileSync(DEVICE_FILE, JSON.stringify(meta, null, 2));
+  chmodSync(DEVICE_FILE, 0o600);
+  return loadDevice();
+}
+
+// Returns a record with the private key + token hydrated from the keychain.
+export function loadDevice() {
+  if (!existsSync(DEVICE_FILE)) return null;
+  const meta = JSON.parse(readFileSync(DEVICE_FILE, 'utf8'));
+  return {
+    ...meta,
+    privateKeyPem: getSecret(`${meta.deviceId}:privkey`),
+    token: getSecret(`${meta.deviceId}:token`) || null,
+  };
+}
+
+// Persist the issued device token into the keychain (not the plaintext file).
+export function saveToken(deviceId, token) {
+  setSecret(`${deviceId}:token`, token);
+  const meta = JSON.parse(readFileSync(DEVICE_FILE, 'utf8'));
+  meta.hasToken = true;
+  writeFileSync(DEVICE_FILE, JSON.stringify(meta, null, 2));
+}
+
+export function purgeDevice(deviceId) {
+  deleteSecret(`${deviceId}:privkey`);
+  deleteSecret(`${deviceId}:token`);
+}
+
+// Sign an arbitrary payload object; returns base64 signature over its canonical JSON.
+export function signPayload(privateKeyPem, payload) {
+  const key = createPrivateKey(privateKeyPem);
+  const msg = Buffer.from(canonical(payload));
+  return edSign(null, msg, key).toString('base64');
+}
+
+// Used by the server side too (re-exported for tests).
+export function publicKeyFromPem(pem) {
+  return createPublicKey(pem);
+}
+
+// Deterministic JSON so client and server hash/sign the exact same bytes.
+export function canonical(obj) {
+  if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
+  if (Array.isArray(obj)) return '[' + obj.map(canonical).join(',') + ']';
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonical(obj[k])).join(',') + '}';
+}
+
+function cryptoRandomId() {
+  // 16 random bytes hex, no Math.random.
+  return Buffer.from(generateKeyPairSync('ed25519').publicKey.export({ type: 'spki', format: 'der' }))
+    .subarray(-8).toString('hex');
+}
+function nowIso() { return new Date().toISOString(); }
+export { DEVICE_FILE, DIR };

package/src/index.mjs

@@ -0,0 +1,9 @@
+// Lull client — public programmatic API (for embedding/testing).
+// The primary entrypoint is the CLI (bin/lull.mjs); this re-exports the building blocks.
+export { createDevice, loadDevice, saveToken, purgeDevice, signPayload } from './identity.mjs';
+export { installStatusLine, uninstallStatusLine, isInstalled, agentStatus } from './config.mjs';
+export { detectAgents, getAdapter, ADAPTERS } from './adapters.mjs';
+export { keychainBackend } from './keychain.mjs';
+export { getPrefs, setPref, getBase } from './prefs.mjs';
+export { tick, commitCreative, resetRuntime } from './runtime.mjs';
+export { api } from './api.mjs';

package/src/keychain.mjs

@@ -0,0 +1,110 @@
+// Lull client — OS keychain storage for secrets (device private key + token).
+//   macOS:   native `security` keychain
+//   Linux:   `secret-tool` (libsecret) when a usable keyring is present
+//   Windows / headless / anything else: a 0600 file in ~/.lull (clearly less safe; we mark it)
+//
+// Robustness rules (these are what make it work across machines, not just on a dev's mac):
+//   - If a native backend FAILS at write time (locked keyring, no D-Bus, CI), we fall back to the
+//     file store instead of silently losing the secret (which would brick the device).
+//   - Reads always consult the file fallback too, so a secret written via fallback is still found.
+//   - `LULL_KEYCHAIN=file|macos|linux|auto` forces a backend (file is handy for CI / containers).
+//
+// Non-secret metadata (deviceId, public key) lives in ~/.lull/device.json — never here.
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, unlinkSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+const SERVICE = 'lull';
+const DIR = join(homedir(), '.lull');
+const FALLBACK = join(DIR, 'secrets.json');
+
+function ensureDir() { if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true, mode: 0o700 }); }
+
+// Run a command, capturing whether it actually succeeded (exit 0). `ok:false` means "it threw or
+// exited non-zero" — distinct from a command that succeeds with empty output (e.g. `secret-tool store`).
+function run(cmd, args, input) {
+  try { return { ok: true, out: execFileSync(cmd, args, { input, stdio: ['pipe', 'pipe', 'ignore'] }).toString() }; }
+  catch { return { ok: false, out: null }; }
+}
+
+function commandExists(cmd) {
+  // Portable presence check that doesn't depend on `which` being installed.
+  return run(process.platform === 'win32' ? 'where' : 'command', process.platform === 'win32' ? [cmd] : ['-v', cmd]).ok
+    || run(cmd, ['--version']).ok;
+}
+
+function backend() {
+  const forced = (process.env.LULL_KEYCHAIN || '').toLowerCase();
+  if (['file', 'macos', 'linux'].includes(forced)) return forced;
+  if (platform() === 'darwin') return 'macos';
+  if (platform() === 'linux' && commandExists('secret-tool')) return 'linux';
+  return 'file';
+}
+
+// Secrets are base64-encoded before storage. This keeps them single-line — critical on macOS,
+// where `security -w` returns HEX (not the raw value) if the stored data contains newlines.
+const encv = (v) => Buffer.from(v, 'utf8').toString('base64');
+const decv = (v) => Buffer.from(v, 'base64').toString('utf8');
+
+// ---- file fallback (also the durable store when a native write fails) ----
+function fileSet(account, stored) {
+  ensureDir();
+  const all = existsSync(FALLBACK) ? JSON.parse(readFileSync(FALLBACK, 'utf8')) : {};
+  all[account] = stored;
+  writeFileSync(FALLBACK, JSON.stringify(all));
+  try { chmodSync(FALLBACK, 0o600); } catch { /* chmod is a no-op/unsupported on some Windows FS */ }
+}
+function fileGet(account) {
+  if (!existsSync(FALLBACK)) return null;
+  try { return JSON.parse(readFileSync(FALLBACK, 'utf8'))[account] || null; } catch { return null; }
+}
+function fileDel(account) {
+  if (!existsSync(FALLBACK)) return;
+  try {
+    const all = JSON.parse(readFileSync(FALLBACK, 'utf8')); delete all[account];
+    if (Object.keys(all).length) writeFileSync(FALLBACK, JSON.stringify(all)); else unlinkSync(FALLBACK);
+  } catch { /* ignore */ }
+}
+
+export function setSecret(account, value) {
+  const b = backend();
+  const stored = encv(value);
+  if (b === 'macos') {
+    const r = run('security', ['add-generic-password', '-U', '-a', account, '-s', SERVICE, '-w', stored]);
+    if (r.ok) return 'macos-keychain';
+    fileSet(account, stored); return 'file-0600 (keychain unavailable)';
+  }
+  if (b === 'linux') {
+    const r = run('secret-tool', ['store', '--label=Lull', 'service', SERVICE, 'account', account], stored);
+    if (r.ok) return 'libsecret';
+    fileSet(account, stored); return 'file-0600 (libsecret unavailable)';
+  }
+  fileSet(account, stored);
+  return 'file-0600';
+}
+
+export function getSecret(account) {
+  const b = backend();
+  let stored = null;
+  if (b === 'macos') {
+    const r = run('security', ['find-generic-password', '-a', account, '-s', SERVICE, '-w']);
+    stored = r.ok && r.out ? r.out.trim() : null;
+  } else if (b === 'linux') {
+    const r = run('secret-tool', ['lookup', 'service', SERVICE, 'account', account]);
+    stored = r.ok && r.out ? r.out.trim() : null;
+  }
+  if (!stored) stored = fileGet(account);   // always consult the fallback (native write may have failed earlier)
+  if (!stored) return null;
+  try { return decv(stored); } catch { return stored; }   // tolerate legacy plaintext
+}
+
+export function deleteSecret(account) {
+  const b = backend();
+  if (b === 'macos') run('security', ['delete-generic-password', '-a', account, '-s', SERVICE]);
+  else if (b === 'linux') run('secret-tool', ['clear', 'service', SERVICE, 'account', account]);
+  fileDel(account);   // also clear the fallback so a secret can't linger after delete
+}
+
+export function keychainBackend() { return backend(); }

package/src/prefs.mjs

@@ -0,0 +1,59 @@
+// Lull client — persistent preferences (~/.lull/config.json).
+// Holds the backend base URL and the dev's display controls. Read by the CLI, the status-line
+// client, and (via settings) the editor extension. Env vars override the file for one-offs.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DIR = join(homedir(), '.lull');
+const FILE = join(DIR, 'config.json');
+
+const DEFAULTS = {
+  base: 'http://localhost:8787',
+  adSeconds: 8,        // how long a sponsor line stays up per display
+  restSeconds: 22,     // quiet gap between sponsor lines — "gets out of the way"
+  maxPerHour: 20,      // frequency cap: never show more than this many sponsor lines/hour
+  enabled: true,
+  blockedCategories: [], // ad categories this dev refuses (their inventory, their veto)
+  spinnerMode: 'replace', // 'replace' | 'append' | 'off' — sponsor line in the "thinking" spinner
+  slEverySeconds: 20,     // throttle for premium status-line day-slot impressions
+  showEarnings: true,     // show live "$X today · $Y total" in the status line during quiet phases
+  country: '',            // SELF-DECLARED country (ISO-2, e.g. IN) for country-targeted sponsors.
+                          // Optional. We never geolocate you — unset means worldwide ads only.
+};
+
+export function getPrefs() {
+  let saved = {};
+  if (existsSync(FILE)) { try { saved = JSON.parse(readFileSync(FILE, 'utf8')); } catch {} }
+  return { ...DEFAULTS, ...saved };
+}
+
+export function setPref(key, value) {
+  if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  const p = getPrefs();
+  // coerce numeric prefs
+  if (['adSeconds', 'restSeconds', 'maxPerHour'].includes(key)) value = Number(value);
+  if (key === 'enabled' || key === 'showEarnings') value = value === true || value === 'true';
+  if (key === 'country') { value = String(value).toUpperCase().trim(); if (!/^([A-Z]{2})?$/.test(value)) throw new Error('country must be a 2-letter ISO code (e.g. IN) or empty'); }
+  p[key] = value;
+  const out = {}; for (const k of Object.keys(DEFAULTS)) out[k] = p[k];
+  writeFileSync(FILE, JSON.stringify(out, null, 2));
+  return out;
+}
+
+// Base URL precedence: env override > saved config > default.
+export function getBase() {
+  return process.env.LULL_BASE || getPrefs().base;
+}
+
+export function blockCategory(cat) {
+  const p = getPrefs(); const set = new Set(p.blockedCategories); set.add(cat);
+  return setPref('blockedCategories', [...set]);
+}
+export function unblockCategory(cat) {
+  const p = getPrefs(); const set = new Set(p.blockedCategories); set.delete(cat);
+  return setPref('blockedCategories', [...set]);
+}
+
+export { FILE as PREFS_FILE };

package/src/render-core.mjs

@@ -0,0 +1,76 @@
+// Lull client — shared render core for every agent surface.
+// Runs one display-cycle tick, reports the qualified (signed) impression, and returns the
+// rendered sponsor line as an OSC-8 clickable hyperlink — or '' during the quiet/rest phase.
+// The OUTPUT TARGET differs per surface and is the caller's job:
+//   • Claude Code  → write the returned string to stdout (Claude renders it in the status line)
+//   • Codex CLI    → write it to the controlling terminal (/dev/tty) from a hook
+// Keeping the decision/report/fetch logic here means every agent shares identical, audited behavior.
+
+import { signPayload } from './identity.mjs';
+import { api } from './api.mjs';
+import { setSpinnerVerbs } from './config.mjs';
+import { tick, commitCreative, walletCache, walletDue } from './runtime.mjs';
+import { randomUUID } from 'node:crypto';
+
+function reportImpression(device, creativeId, dwellMs) {
+  const payload = { deviceId: device.deviceId, creativeId, dwellMs: Math.round(dwellMs), nonce: randomUUID(), ts: new Date().toISOString() };
+  try { api.reportImpression(payload, signPayload(device.privateKeyPem, payload)).catch(() => {}); } catch {}
+}
+
+export function label(text) { return `▸ Sponsored · ${text} · getlull.dev`; }
+
+// OSC 8 terminal hyperlink: the sponsor line becomes clickable → a tracked redirect that bills
+// the click (CPC) and forwards the dev to the advertiser. Plain text in terminals without OSC-8.
+export function renderLine(device, creative) {
+  const cid = creative.campaignId || 'house';
+  const url = `${api.base}/c/${encodeURIComponent(cid)}?device=${encodeURIComponent(device.deviceId)}`;
+  return `\x1b]8;;${url}\x07${label(creative.text)}\x1b]8;;\x07`;
+}
+
+// Dim "live earnings" line for the persistent status line, e.g. "⚡ Lull · $0.42 today · $7.11".
+// Small balances keep 4 decimals so the number visibly ticks; larger ones round to cents.
+function fmtUsd(v) { const n = Number(v); if (!isFinite(n)) return null; return n >= 1 ? n.toFixed(2) : n.toFixed(4); }
+async function earningsLine(device, prefs) {
+  if (prefs.showEarnings === false) return '';
+  // Refresh on a slow throttle; the status-line process is short-lived so we must await the fetch
+  // (a background promise would be killed on exit), but it only happens ~once/minute.
+  if (walletDue()) {
+    try {
+      const w = await api.wallet(device.deviceId);
+      if (w && w.balanceUsd != null) walletCache({ totalUsd: w.balanceUsd, todayUsd: w.todayUsd ?? null });
+    } catch { /* keep last cached value */ }
+  }
+  const w = walletCache();
+  const total = w && fmtUsd(w.totalUsd);
+  if (total == null) return '';
+  const today = w.todayUsd != null && fmtUsd(w.todayUsd);
+  const body = today != null ? `$${today} today · $${total} total` : `$${total} earned`;
+  return `\x1b[2m⚡ Lull · ${body} · getlull.dev\x1b[0m`;   // dim, so it never competes with your code
+}
+
+// One display-cycle tick. `setVerbs` is Claude-Code-only (it edits ~/.claude spinnerVerbs);
+// `earnings` fills the quiet phase with the live balance (persistent status line only — NOT the
+// Codex tty, where it would spam a new line each hook). Returns the line to show, or ''.
+export async function produce(device, prefs, { setVerbs = false, earnings = false } = {}) {
+  const decision = tick(prefs);
+
+  // Report impressions: spinner CPM (on dwell) + premium status-line day slot (throttled).
+  if (decision.report) reportImpression(device, decision.report.creativeId, decision.report.dwellMs);
+  if (decision.slReport) reportImpression(device, decision.slReport.creativeId, decision.slReport.dwellMs);
+
+  if (decision.needCreative) {
+    try {
+      const { creative, spinner, statusline } = await api.serve({ deviceId: device.deviceId, blocked: prefs.blockedCategories, country: prefs.country });
+      if (setVerbs && prefs.spinnerMode !== 'off') {
+        try { setSpinnerVerbs((spinner && spinner.length ? spinner : [creative.text]).map(label), prefs.spinnerMode || 'replace'); } catch {}
+      }
+      commitCreative(creative, statusline || null);
+      return renderLine(device, statusline || creative);
+    } catch { return earnings ? earningsLine(device, prefs) : ''; }
+  }
+
+  const show = decision.sl || decision.show;
+  if (show) return renderLine(device, show);
+  // Quiet phase: show the dev their money ticking up instead of a blank line.
+  return earnings ? earningsLine(device, prefs) : '';
+}

package/src/runtime.mjs

@@ -0,0 +1,86 @@
+// Lull client — display-cycle runtime (~/.lull/runtime.json).
+// The status-line command is invoked many times per second by the agent. This module turns that
+// firehose into an HONEST, RESPECTFUL display cycle:
+//
+//   [ ad phase: show one creative for adSeconds ] -> report ONE impression with real dwell
+//   [ rest phase: show nothing for restSeconds  ] -> the line gets out of the way
+//
+// Plus a per-hour frequency cap. State persists across the short-lived status-line processes.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DIR = join(homedir(), '.lull');
+const FILE = join(DIR, 'runtime.json');
+
+function load() {
+  if (!existsSync(FILE)) return { phase: 'rest', phaseStart: 0, creative: null, impressionLog: [] };
+  try { return JSON.parse(readFileSync(FILE, 'utf8')); } catch { return { phase: 'rest', phaseStart: 0, creative: null, impressionLog: [] }; }
+}
+function save(s) {
+  try { if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true, mode: 0o700 }); writeFileSync(FILE, JSON.stringify(s)); } catch {}
+}
+
+// Returns a decision for THIS invocation:
+//   { show: text|null, report: {creativeId, dwellMs} | null, needCreative: bool }
+// Caller fetches a creative when needCreative is true, then calls commitCreative().
+export function tick(prefs, now = Date.now()) {
+  const s = load();
+  const adMs = prefs.adSeconds * 1000;
+  const restMs = prefs.restSeconds * 1000;
+
+  // rolling 1h impression count for the frequency cap
+  s.impressionLog = (s.impressionLog || []).filter((t) => now - t < 3_600_000);
+  const overCap = s.impressionLog.length >= prefs.maxPerHour;
+
+  // `sl` is the premium STATUS-LINE day-slot ad — shown CONSTANTLY (separate from the spinner
+  // ad/rest cycle) and reported on a slow throttle (slEvery).
+  const sl = s.sl || null;
+  const slDue = sl && now - (s.slReportAt || 0) >= (prefs.slEverySeconds || 20) * 1000;
+
+  if (s.phase === 'ad' && s.creative) {
+    const elapsed = now - s.phaseStart;
+    if (elapsed >= adMs) {
+      const report = { creativeId: s.creative.id, dwellMs: elapsed };
+      s.impressionLog.push(now);
+      s.phase = 'rest'; s.phaseStart = now; s.creative = null;
+      save(s);
+      return { show: null, report, needCreative: false, sl, slReport: slDue ? slReport(s, sl, now) : null };
+    }
+    return { show: s.creative, report: null, needCreative: false, sl, slReport: slDue ? slReport(s, sl, now) : null };
+  }
+
+  const restedEnough = now - s.phaseStart >= restMs;
+  if (!prefs.enabled || overCap || !restedEnough) {
+    return { show: null, report: null, needCreative: false, sl, slReport: slDue ? slReport(s, sl, now) : null };
+  }
+  return { show: null, report: null, needCreative: true, sl, slReport: slDue ? slReport(s, sl, now) : null };
+}
+
+function slReport(s, sl, now) { s.slReportAt = now; save(s); return { creativeId: sl.id, dwellMs: 5000 }; }
+
+// Caller got a creative for a new ad phase; record it (and the current status-line day-slot ad).
+export function commitCreative(creative, sl = undefined, now = Date.now()) {
+  const s = load();
+  s.phase = 'ad'; s.phaseStart = now; s.creative = creative;
+  if (sl !== undefined) s.sl = sl || null;
+  save(s);
+  return creative.text;
+}
+
+export function resetRuntime() { save({ phase: 'rest', phaseStart: 0, creative: null, sl: null, slReportAt: 0, impressionLog: [] }); }
+
+// Cached wallet snapshot for the live "earnings ticking" status line. The status-line command is
+// short-lived and spawned per render, so we persist the last balance here and only re-fetch on a
+// slow throttle — the render never blocks on the network except once per interval.
+export function walletCache(update, now = Date.now()) {
+  const s = load();
+  if (update) { s.wallet = { ...update, at: now }; save(s); return s.wallet; }
+  return s.wallet || null;
+}
+export function walletDue(intervalMs = 60_000, now = Date.now()) {
+  const s = load();
+  return now - ((s.wallet && s.wallet.at) || 0) >= intervalMs;
+}
+export { FILE as RUNTIME_FILE };

package/src/statusline.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Lull status-line command for Claude Code. Claude invokes this many times/sec and renders our
+// STDOUT in the status line. The shared decision/report/fetch logic lives in render-core.mjs.
+// Privacy: stdin (the agent session JSON) is drained and never inspected — the privacy claim, proven.
+
+import { loadDevice } from './identity.mjs';
+import { getPrefs } from './prefs.mjs';
+import { produce } from './render-core.mjs';
+
+function drainStdin() {
+  return new Promise((resolve) => {
+    let n = 0;
+    process.stdin.on('data', (c) => (n += c.length));
+    process.stdin.on('end', () => resolve(n));
+    setTimeout(() => resolve(n), 40);
+  });
+}
+
+async function main() {
+  await drainStdin();
+  const device = loadDevice();
+  if (!device) { process.stdout.write(''); return; }
+  process.stdout.write(await produce(device, getPrefs(), { setVerbs: true, earnings: true }));
+}
+
+main();