syndes 0.1.0 → 0.3.0

package/dashboard/web/views/team.js

@@ -0,0 +1,496 @@
+/**
+ * Team — one shared account, seen from every machine on it.
+ *
+ * Four questions, in the order two people sharing a plan actually ask them:
+ *   1. Whose share is it?        the split, and which way it moved
+ *   2. What is the pool doing?   totals, and whether the numbers are live
+ *   3. Were we in each other's way?  the contention grid — the one thing
+ *      neither person can see from their own machine
+ *   4. How did each day break down?  the daily split, and the people table
+ *
+ * The page is live while it is open: it holds one event stream, and the server
+ * polls the pool only while that stream exists. When the view is replaced the
+ * stream is closed on the next message, because a detached page must not keep
+ * a connection — or a git remote — busy on its behalf.
+ */
+
+import { api } from '../api.js';
+import {
+  h, card, figure, trend, chip, dot, meter, legend, empty, table, modal,
+  compact, usd, duration, percent, when, DASH,
+} from '../ui.js';
+import { dotMatrix, laneSplit, splitBar } from '../charts.js';
+
+export async function render({ range }) {
+  const data = await api.team(range);
+
+  const outlet = h('div.content--fit', {
+    style: 'display:grid;grid-template-rows:auto minmax(0,1fr);gap:var(--s4);min-height:0',
+  });
+
+  if (!data.enabled) {
+    outlet.style.display = 'grid';
+    outlet.style.gridTemplateRows = 'minmax(0,1fr)';
+    outlet.appendChild(setup(range, outlet));
+    return outlet;
+  }
+
+  paint(outlet, data, range);
+  connect(outlet, range);
+  return outlet;
+}
+
+// ── Live ────────────────────────────────────────────────────────────────────
+
+/**
+ * The event stream.
+ *
+ * Reconnection is EventSource's own job, which is most of why it was chosen
+ * over a socket. The one thing it will not do is notice that the page it was
+ * opened for no longer exists — so every message checks, and the last one closes
+ * it. Without that, switching to another view leaves the server polling git
+ * forever for an audience of nobody.
+ */
+function connect(outlet, range) {
+  let source;
+  try {
+    source = new EventSource(api.teamStreamUrl(range));
+  } catch {
+    return; // no stream is a static page, not a broken one
+  }
+
+  const stop = () => { try { source.close(); } catch { /* already closed */ } };
+
+  const onData = (event) => {
+    if (!outlet.isConnected) return stop();
+    let data;
+    try { data = JSON.parse(event.data); } catch { return; }
+    paint(outlet, data, range, { live: true });
+  };
+
+  source.addEventListener('snapshot', onData);
+  source.addEventListener('update', onData);
+  source.addEventListener('error', () => { if (!outlet.isConnected) stop(); });
+  window.addEventListener('beforeunload', stop, { once: true });
+}
+
+// ── The page ────────────────────────────────────────────────────────────────
+
+function paint(outlet, data, range, { live = false } = {}) {
+  const me = data.peers.find((peer) => peer.isMe) ?? null;
+
+  outlet.replaceChildren(
+    h('div.grid.g-3', {}, [shareCard(data, me), poolCard(data, live), contentionCard(data)]),
+    h('div.grid.fill', { style: 'grid-template-columns:minmax(0,1.1fr) minmax(0,1fr)' }, [
+      splitCard(data),
+      peopleCard(data, outlet, range),
+    ]),
+  );
+}
+
+// 1. Whose share is it
+function shareCard(data, me) {
+  const share = me?.share ?? 0;
+  const fair = data.peers.length ? 1 / data.peers.length : 1;
+
+  return card('Your share', [
+    h('div', { style: 'display:flex;align-items:flex-end;gap:var(--s5);flex-wrap:wrap' }, [
+      figure('of the pool this period', percent(share), {
+        trend: me ? trend(share, share - (me.shareDelta ?? 0), {
+          format: (value) => percent(value),
+          // More of a shared window is not "good" — it is more, and whether that
+          // is fine is between the people sharing it. So the arrow is drawn
+          // neutral rather than scoring one of them for using less.
+          goodDirection: 'up',
+          suffix: 'vs last period',
+        }) : null,
+      }),
+      h('div', { style: 'display:grid;gap:4px' }, [
+        h('span.card__note', { text: `Even split would be ${percent(fair)}` }),
+        h('span.card__note', {
+          text: `${compact(me?.totals.tokens ?? 0)} of ${compact(data.totals.tokens)} tokens`,
+        }),
+      ]),
+    ]),
+
+    splitBar(data.peers.map((peer) => ({
+      label: peer.name, value: peer.totals.tokens, isMe: peer.isMe,
+    })), { label: 'share of the pool by person' }),
+
+    legend([
+      { tone: 'lime', label: 'you' },
+      { tone: 'white', label: 'everyone else' },
+    ], compact(data.totals.tokens)),
+  ]);
+}
+
+// 2. What is the pool doing
+function poolCard(data, live) {
+  const sync = data.sync ?? {};
+  const failed = sync.ok === false && sync.error;
+
+  return card('The pool', [
+    h('div.grid', { style: 'grid-template-columns:1fr 1fr;gap:var(--s4)' }, [
+      figure('people', String(data.totals.people), { small: true }),
+      figure('tokens', compact(data.totals.tokens), {
+        small: true,
+        trend: trend(data.totals.tokens, data.totals.tokens - (data.totals.deltaTokens ?? 0), { format: compact }),
+      }),
+      figure('active time', duration(data.totals.activeMs), { small: true }),
+      figure('notional cost', usd(data.totals.usd), { small: true }),
+    ]),
+
+    h('div', { style: 'display:grid;gap:6px;margin-top:auto' }, [
+      h('div', { style: 'display:flex;align-items:center;gap:8px' }, [
+        dot(failed ? 'orange' : live ? 'lime' : 'white'),
+        h('span.card__note', {
+          text: failed
+            ? 'Last sync failed'
+            : live ? `Live · refreshing every ${data.config.pollSeconds}s` : 'Connecting…',
+        }),
+      ]),
+      h('span.card__note', { text: `Last exchange ${sync.at ? when(sync.at) : DASH}` }),
+      failed ? h('span.card__note', { style: 'color:var(--orange)', text: String(sync.error).slice(0, 120) }) : null,
+      h('span.card__note', {
+        // Said plainly on the page rather than buried in a doc: on a shared plan
+        // the dollars are what these tokens WOULD have cost at API rates, and
+        // presenting an estimate as a bill would be the wrong kind of confident.
+        text: 'Cost is notional — a shared plan bills a subscription, not tokens.',
+      }),
+    ]),
+  ]);
+}
+
+// 3. Were we in each other's way
+function contentionCard(data) {
+  const grid = data.grid;
+  const overlapping = grid.overlapBands > 0;
+
+  return card('When each of you worked', [
+    h('div', { style: 'display:flex;align-items:baseline;gap:var(--s3)' }, [
+      figure('of working hours overlapped', percent(grid.overlapRate), { small: true }),
+      overlapping ? chip(`${grid.overlapBands} bands`, 'orange') : chip('no overlap', 'lime'),
+    ]),
+    dotMatrix(grid),
+    legend([
+      { tone: 'lime', label: 'one person had the window' },
+      { tone: 'orange', label: 'two or more at once' },
+    ]),
+    h('span.card__note', {
+      text: overlapping
+        ? 'Orange bands are where you were both spending the same rate limit.'
+        : 'Nobody has collided in this period.',
+    }),
+  ], { note: `${grid.bandHours}-hour bands` });
+}
+
+// 4a. How did each day break down
+function splitCard(data) {
+  const rows = data.lanes.filter((row) => row.total > 0);
+  if (!rows.length) return card('Daily split', [empty('No shared activity in this range yet.')]);
+
+  return card('Daily split', [
+    h('div.card__scroll', {}, [
+      laneSplit(rows, { format: compact }),
+    ]),
+    legend([
+      { tone: 'lime', label: 'you' },
+      { tone: 'white', label: 'everyone else' },
+    ], compact(data.totals.tokens)),
+  ], { note: 'newest first' });
+}
+
+// 4b. The people
+function peopleCard(data, outlet, range) {
+  const rows = data.peers.map((peer) => [
+    h('div', { style: 'display:flex;align-items:center;gap:9px;min-width:0' }, [
+      h('span.avatar', { text: peer.initials, title: peer.host ?? peer.deviceId }),
+      h('div', { style: 'display:grid;min-width:0' }, [
+        h('span', {
+          style: 'font-weight:650;overflow:hidden;text-overflow:ellipsis;white-space:nowrap',
+          text: peer.name,
+        }),
+        h('span.card__note', { text: peer.isMe ? 'this machine' : (peer.host ?? DASH) }),
+      ]),
+      peer.stale ? chip('stale', 'orange') : null,
+    ]),
+    h('div', { style: 'display:grid;gap:5px;min-width:90px' }, [
+      h('span.tnum', { style: 'font-size:12px', text: percent(peer.share) }),
+      meter(peer.share, peer.isMe ? 'lime' : 'white'),
+    ]),
+    compact(peer.totals.tokens),
+    String(peer.totals.sessions),
+    duration(peer.totals.activeMs),
+    peer.score === null ? DASH : String(peer.score),
+    peer.isMe
+      ? h('span', { style: 'color:var(--ink-3)', text: DASH })
+      : h('button.btn.btn--ghost.btn--sm', {
+          text: 'Remove',
+          title: `Remove ${peer.name} from the pool`,
+          onclick: () => remove(peer, outlet, range),
+        }),
+  ]);
+
+  const actions = h('div', { style: 'display:flex;gap:8px' }, [
+    h('button.btn.btn--lime', { text: 'Invite', onclick: () => invite() }),
+    h('button.btn.btn--ghost', { text: 'Rename', onclick: () => rename(data, outlet, range) }),
+    h('button.btn.btn--ghost', { text: 'Sync now', onclick: () => syncNow(outlet, range) }),
+  ]);
+
+  return card('People', [
+    table(
+      ['Person', 'Share', 'Tokens', 'Sessions', 'Active', 'Score', ''],
+      rows,
+      { align: ['left', 'left', 'right', 'right', 'right', 'right', 'right'] },
+    ),
+    h('span.card__note', {
+      text: 'A stale shelf has not synced in six hours — that is a machine that stopped reporting, not a quiet day.',
+    }),
+    h('div', { style: 'margin-top:auto;display:flex;gap:8px;flex-wrap:wrap' }, [
+      h('button.btn.btn--ghost', { text: `Sharing: ${data.config.scope}`, onclick: () => changeScope(data, outlet, range) }),
+      h('button.btn.btn--ghost', { text: 'Leave pool', onclick: () => leavePool(outlet, range) }),
+    ]),
+  ], { actions });
+}
+
+// ── Actions ─────────────────────────────────────────────────────────────────
+
+/**
+ * Invite someone.
+ *
+ * The output is one line they paste into a terminal — not a URL and a list of
+ * steps. Everything they would otherwise have to be told (install it, sign in
+ * to GitHub, paste the repo, pick a name) is what `syndes join` then does for
+ * them, so the thing being copied here is the whole onboarding.
+ *
+ * The two facts that are easy to get wrong are stated in the dialog rather than
+ * left for someone to discover: the invite is not a key, and a pool is one room
+ * where everybody can see everybody.
+ */
+async function invite() {
+  let details;
+  try {
+    details = await api.teamInvite();
+  } catch (error) {
+    await modal({ title: 'Could not make an invite', note: error.body?.error ?? error.message, confirmLabel: 'Close', cancelLabel: 'Dismiss' });
+    return;
+  }
+
+  const box = h('code.invite', { text: details.command });
+  const copy = h('button.btn.btn--lime', { type: 'button', text: 'Copy the line' });
+  copy.addEventListener('click', async () => {
+    try {
+      await navigator.clipboard.writeText(details.command);
+      copy.textContent = 'Copied';
+    } catch {
+      // Clipboard access can be refused; selecting the text still works.
+      copy.textContent = 'Select it and copy';
+    }
+    setTimeout(() => { copy.textContent = 'Copy the line'; }, 2200);
+  });
+
+  await modal({
+    title: `Invite someone to ${details.pool}`,
+    note: 'Send them this line. It installs SynDes, checks their GitHub access, offers to fix it, and joins them.',
+    body: [
+      box,
+      h('div', { style: 'display:flex;justify-content:center' }, [copy]),
+      h('div.modal__note', { style: 'text-align:left;margin-top:4px' }, [
+        h('div', { text: `1. Add them as a collaborator on ${details.repo}` }),
+        h('div', { text: '2. They accept the invite on GitHub' }),
+        h('div', { text: '3. They paste the line above' }),
+      ]),
+      h('div.modal__note', { style: 'text-align:left;color:var(--orange)' }, [
+        h('div', { text: 'Everyone in a pool can see everyone else in it — names, hours and volumes.' }),
+        h('div', { text: 'The line is not a key. Access is the repository\'s collaborator list, and only that.' }),
+      ]),
+    ],
+    confirmLabel: 'Done',
+    cancelLabel: 'Close',
+  });
+}
+
+async function remove(peer, outlet, range) {
+  const ok = await modal({
+    title: `Remove ${peer.name}?`,
+    note: `This takes their published days out of the pool for everyone, so past totals will change. Their own ledger is untouched.`,
+    body: [
+      h('div.modal__note', { style: 'text-align:left' }, [
+        h('div', { text: 'Git keeps the old commits, so this removes them from view, not from history.' }),
+        h('div', { text: 'To stop them publishing more, remove their access to the repository as well.' }),
+      ]),
+    ],
+    confirmLabel: `Remove ${peer.name}`,
+    cancelLabel: 'Keep them',
+    danger: true,
+  });
+  if (!ok) return;
+
+  try {
+    const result = await api.teamRemove(peer.deviceId);
+    if (!result.pushed) {
+      await modal({
+        title: 'Removed here, but not pushed',
+        note: result.error ?? 'The change is local until a push succeeds. Try Sync now.',
+        confirmLabel: 'Close', cancelLabel: 'Dismiss',
+      });
+    }
+  } catch (error) {
+    await modal({ title: 'Could not remove', note: error.body?.error ?? error.message, confirmLabel: 'Close', cancelLabel: 'Dismiss' });
+  }
+  await refresh(outlet, range);
+}
+
+async function rename(data, outlet, range) {
+  const name = await modal({
+    title: 'What should this machine be called?',
+    note: 'This is the only name anyone in the pool sees. It is yours to choose.',
+    confirmLabel: 'Save',
+    input: {
+      value: data.me.name,
+      maxlength: 40,
+      placeholder: 'Your name',
+      validate: (value) => (value.trim() ? null : 'A name cannot be empty.'),
+    },
+  });
+  if (name === null) return;
+  await api.teamAction('name', { name });
+  await refresh(outlet, range);
+}
+
+async function changeScope(data, outlet, range) {
+  const next = data.config.scope === 'summary' ? 'detailed' : 'summary';
+  const ok = await modal({
+    title: next === 'detailed' ? 'Share more detail?' : 'Share less detail?',
+    note: next === 'detailed'
+      ? 'Detailed adds your project ids and tool mix to what the pool can see. Prompt text is never shared at any setting.'
+      : 'Summary shares counts, tokens and hours only. No project ids, no tool names.',
+    confirmLabel: `Switch to ${next}`,
+  });
+  if (!ok) return;
+  await api.teamAction('scope', { scope: next });
+  await refresh(outlet, range);
+}
+
+async function leavePool(outlet, range) {
+  const ok = await modal({
+    title: 'Leave the pool?',
+    note: 'Your shelf stays where it is until someone deletes it. Your own ledger is untouched.',
+    confirmLabel: 'Leave',
+  });
+  if (!ok) return;
+  await api.teamAction('leave');
+  await refresh(outlet, range);
+}
+
+async function syncNow(outlet, range) {
+  await api.teamAction('sync');
+  await refresh(outlet, range);
+}
+
+async function refresh(outlet, range) {
+  const data = await api.team(range);
+  if (!outlet.isConnected) return;
+  if (!data.enabled) {
+    outlet.replaceChildren(setup(range, outlet));
+    return;
+  }
+  paint(outlet, data, range, { live: true });
+}
+
+// ── Setup ───────────────────────────────────────────────────────────────────
+
+/**
+ * Joining a pool.
+ *
+ * Stated up front, before the field: what leaves the machine, and what does
+ * not. Somebody about to point their working history at a git remote is owed
+ * that in the same breath as the input box, not in a settings page they will
+ * never open.
+ */
+function setup(range, outlet) {
+  const repo = h('input.field', {
+    type: 'text',
+    placeholder: 'git@github.com:you/team-usage.git',
+    autocomplete: 'off',
+    spellcheck: 'false',
+  });
+  const name = h('input.field', { type: 'text', placeholder: 'Your name', maxlength: '40', autocomplete: 'off' });
+  const error = h('div.unlock__error', { role: 'alert' });
+  const button = h('button.btn.btn--lime', { type: 'submit', text: 'Join the pool' });
+
+  const form = h('form', { style: 'display:grid;gap:var(--s4)' }, [
+    h('label', { style: 'display:grid;gap:6px' }, [
+      h('span.figure__label', { text: 'Repository' }),
+      repo,
+      h('span.card__note', { text: 'A private repo everyone sharing the account can push to. Your own git credentials are used — SynDes never sees a token.' }),
+    ]),
+    h('label', { style: 'display:grid;gap:6px' }, [
+      h('span.figure__label', { text: 'Your name' }),
+      name,
+    ]),
+    button,
+    error,
+  ]);
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const url = repo.value.trim();
+    if (!url) { error.textContent = 'A repository url is required.'; return; }
+
+    button.disabled = true;
+    button.textContent = 'Joining…';
+    try {
+      if (name.value.trim()) await api.teamAction('name', { name: name.value.trim() });
+      await api.teamAction('join', { transport: transportFor(url), repo: url });
+      await refresh(outlet, range);
+    } catch (caught) {
+      error.textContent = caught.body?.error ?? 'Could not reach that repository.';
+      button.disabled = false;
+      button.textContent = 'Join the pool';
+    }
+  });
+
+  return h('div', { style: 'display:grid;place-items:center;height:100%;overflow-y:auto' }, [
+    h('div', { style: 'width:min(560px,100%);display:grid;gap:var(--s5)' }, [
+      h('div', { style: 'display:grid;gap:10px' }, [
+        h('div', {
+          style: 'font-size:24px;font-weight:750;letter-spacing:-0.02em;text-transform:uppercase',
+          text: 'One account, several people',
+        }),
+        h('p.unlock__note', {
+          style: 'margin:0;text-align:left;line-height:1.7',
+          text: 'Each machine writes its own numbers into a shared repository and reads everyone else’s. Nobody writes anyone else’s file, so there is nothing to merge and no server to run.',
+        }),
+      ]),
+
+      card('What leaves this machine', [
+        h('div', { style: 'display:grid;gap:9px' }, [
+          shared(true, 'Daily counts: tokens, sessions, prompts, tool calls, active time'),
+          shared(true, 'The hours of the day you worked, so overlap can be spotted'),
+          shared(false, 'Your prompts. Never, at any setting.'),
+          shared(false, 'File paths, commands, project names — not at the default setting'),
+        ]),
+      ]),
+
+      form,
+    ]),
+  ]);
+}
+
+function shared(yes, text) {
+  return h('div', { style: 'display:flex;align-items:flex-start;gap:10px;font-size:12px;color:var(--ink-2)' }, [
+    h('span', {
+      style: `flex:none;margin-top:1px;font-weight:800;color:var(--${yes ? 'lime' : 'orange'})`,
+      text: yes ? '+' : '−',
+      'aria-hidden': 'true',
+    }),
+    h('span', { text }),
+  ]);
+}
+
+/** A path is a folder pool; anything with a scheme or a colon is a git remote. */
+function transportFor(url) {
+  if (/^(https?:\/\/|git@|ssh:\/\/|git:\/\/)/.test(url)) return 'git';
+  return url.endsWith('.git') ? 'git' : 'folder';
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "syndes",
-  "version": "0.1.0",
-  "description": "SynDes \u2014 a tamper-evident ledger of everything you do in Claude Code, an efficiency score built from it, and a local dashboard that shows you how you actually work. macOS, Windows and Linux. Zero dependencies.",
+  "version": "0.3.0",
+  "description": "SynDes — a tamper-evident ledger of everything you do in Claude Code, an efficiency score built from it, and a local dashboard that shows you how you actually work. Splits one shared account between the people on it. macOS, Windows and Linux. Zero dependencies.",
   "keywords": [
     "syndes",
     "claude",
@@ -20,7 +20,10 @@
     "macos",
     "windows",
     "linux",
-    "cli"
+    "cli",
+    "team",
+    "shared-account",
+    "multi-user"
   ],
   "license": "MIT",
   "type": "module",
@@ -39,7 +42,8 @@
     "notify",
     "practices",
     "runtime",
-    "src"
+    "src",
+    "sync"
   ],
   "engines": {
     "node": ">=18.0.0"

package/runtime/config.mjs

@@ -46,6 +46,23 @@ export const DEFAULTS = {
     gzipAfterDays: 30,
   },
 
+  /**
+   * Sharing, off until someone turns it on.
+   *
+   * `scope` governs what leaves the machine and defaults to the narrower of the
+   * two. Raising it is a decision a person makes about their own data, so it is
+   * never raised for them — not by an upgrade, and not by joining a pool.
+   */
+  team: {
+    enabled: false,
+    transport: null,   // 'git' | 'folder'
+    repo: null,        // a remote url, or the path of a synced folder
+    scope: 'summary',  // 'summary' | 'detailed' — never prompt text, at any scope
+    pollSeconds: 30,   // how often an OPEN dashboard refreshes the pool
+    syncMinutes: 10,   // how often the worker exchanges with no dashboard open
+    shareDays: 45,     // how much history our shelf keeps, so the pool stays bounded
+  },
+
   /** Gap below which two events count as continuous work, for active time. */
   idleGapMinutes: 5,
 };

package/runtime/identity.mjs

@@ -0,0 +1,96 @@
+/**
+ * Who this machine is, and what to call the person sitting at it.
+ *
+ * A shared pool needs a stable name for each shelf, and the obvious candidates
+ * are all wrong: a hostname changes when someone renames their laptop, an OS
+ * username collides across machines, and a path is not an identity. So the id is
+ * minted once, at random, and kept — a rename then changes the label without
+ * orphaning a month of history under an id nobody recognises.
+ *
+ * The display name is the user's to choose. It is the only field in this whole
+ * system that a human types about themselves, so it is never inferred from
+ * anything that might be an email address or a real name they did not offer.
+ */
+
+import { hostname, userInfo, platform, release } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { deviceFile } from './paths.mjs';
+
+let cached = null;
+
+/** @returns {{deviceId: string, name: string, host: string, os: string, createdAt: number}} */
+export function identity() {
+  if (cached) return cached;
+
+  let stored = null;
+  try {
+    stored = JSON.parse(readFileSync(deviceFile, 'utf8'));
+  } catch {
+    stored = null;
+  }
+
+  if (!stored?.deviceId) {
+    stored = {
+      deviceId: randomBytes(8).toString('hex'),
+      name: null,
+      createdAt: Date.now(),
+    };
+    persist(stored);
+  }
+
+  cached = {
+    deviceId: stored.deviceId,
+    // Falls back to the account name only because a shelf with no label is
+    // unreadable in a list. `syndes team name <you>` replaces it.
+    name: stored.name || safeUser(),
+    host: safeHost(),
+    os: `${platform()} ${release()}`.slice(0, 40),
+    createdAt: stored.createdAt ?? Date.now(),
+  };
+  return cached;
+}
+
+export function setName(name) {
+  const clean = String(name ?? '').trim().slice(0, 40);
+  if (!clean) throw new Error('a name cannot be empty');
+
+  let stored = {};
+  try { stored = JSON.parse(readFileSync(deviceFile, 'utf8')); } catch { /* first run */ }
+  stored.deviceId ??= randomBytes(8).toString('hex');
+  stored.createdAt ??= Date.now();
+  stored.name = clean;
+  persist(stored);
+  cached = null;
+  return identity();
+}
+
+/** Two initials for the avatar chips. Ascii only — the chart draws them as SVG text. */
+export function initialsOf(name) {
+  const words = String(name ?? '').trim().split(/[\s._-]+/).filter(Boolean);
+  if (!words.length) return '??';
+  if (words.length === 1) return words[0].slice(0, 2).toUpperCase();
+  return (words[0][0] + words[words.length - 1][0]).toUpperCase();
+}
+
+function persist(record) {
+  try {
+    mkdirSync(dirname(deviceFile), { recursive: true });
+    writeFileSync(deviceFile, `${JSON.stringify(record, null, 2)}\n`);
+  } catch {
+    // An unwritable state directory costs a stable id, never a session.
+  }
+}
+
+function safeUser() {
+  try { return userInfo().username?.slice(0, 40) || 'unnamed'; } catch { return 'unnamed'; }
+}
+
+function safeHost() {
+  try { return hostname().split('.')[0].slice(0, 40); } catch { return 'unknown'; }
+}
+
+export function resetCache() {
+  cached = null;
+}

package/runtime/paths.mjs

@@ -64,6 +64,18 @@ export const cursorsFile = join(stateDir, 'cursors.json');
 export const sessionsFile = join(stateDir, 'sessions.json');
 export const coachFile = join(stateDir, 'coach.json');
 export const projectsFile = join(stateDir, 'projects.json');
+export const deviceFile = join(stateDir, 'device.json');
+
+// ── Team sharing ────────────────────────────────────────────────────────────
+// The working copy of the shared pool. Disposable: it is a mirror of a remote
+// (or of a synced folder), never a source of truth. Deleting it costs one pull.
+export const teamDir = join(dataDir, 'team');
+export const teamStateFile = join(stateDir, 'team.json');
+
+/** Our own shelf in the pool. A device writes here and NOWHERE else. */
+export function teamDeviceDir(root, deviceId) {
+  return join(root, 'devices', deviceId);
+}
 
 /**
  * Set by the npm postinstall, cleared the first time the CLI runs.