syndes 0.2.0 → 0.3.3

package/README.md

@@ -77,12 +77,31 @@ other people also use.
 
 ## Sharing an account
 
+`syndes install` asks. Or set it up later:
+
 ```bash
 syndes team join git@github.com:you/usage.git   # a private repo you both push to
 syndes team join ~/Dropbox/usage --folder       # or no server at all
-syndes team name "Ada"
 ```
 
+**Adding someone is one line.** `syndes team invite` — or the Invite button on
+the Team page — prints a command you send them:
+
+```
+npm install -g syndes && syndes join syndes1_eyJ2Ijox…
+```
+
+That installs SynDes, works out why git cannot reach the repo, offers to sign
+them in, joins them and starts publishing. The invite carries an address, never
+a credential: who may join is the repository's collaborator list, and only that.
+
+| | |
+| --- | --- |
+| `syndes team invite` | a line to send someone |
+| `syndes team status` | who used how much |
+| `syndes team remove <name>` | take a machine out of the pool |
+| `syndes team doctor` | what is stopping git reaching the repo |
+
 Each machine writes only its own folder and reads everyone's, so there is nothing
 to merge and nothing to run. Open the dashboard and the **Team** page is live
 while you watch it.
@@ -90,6 +109,11 @@ while you watch it.
 What leaves your machine: daily counts, tokens, and the hours you worked. What
 never does: your prompts, your file paths, your commands — at any setting.
 
+**A pool is one room.** Everyone in it sees everyone else — names, hours and
+volumes — and can read the raw files on GitHub without SynDes. Add only people
+who should all see each other. Removing someone takes them out of the view;
+git keeps the old commits, so it is not an erasure.
+
 This is cooperative measurement, not enforcement. It sees Claude Code on machines
 where SynDes is installed, and anyone can stop publishing. Note that consumer
 plans are licensed to one person; per-person logins are both the supported path

package/bin/cli.mjs

@@ -42,7 +42,9 @@ import { openUrl } from '../src/open.mjs';
 import { pendingCount } from '../runtime/spool.mjs';
 import { detectAll, adapterFor, ADAPTERS } from '../adapters/index.mjs';
 import { pollTails, resetCursors } from '../collect/tail.mjs';
-import { joinPool, leave as leavePool, syncOnce, readPool, isEnabled, teamConfig, loadState, poolRoot } from '../sync/index.mjs';
+import { joinPool, leave as leavePool, syncOnce, readPool, isEnabled, teamConfig, loadState, poolRoot, inviteCode, removeDevice, poolName } from '../sync/index.mjs';
+import { decode as decodeInvite, commandFor } from '../sync/invite.mjs';
+import { diagnose as preflight, repair as repairAuth, ghInstallHint } from '../src/preflight.mjs';
 import { identity, setName, initialsOf } from '../runtime/identity.mjs';
 import { team as teamView } from '../analytics/team.mjs';
 
@@ -52,7 +54,7 @@ const COMMANDS = {
   install: cmdInstall, uninstall: cmdUninstall, doctor: cmdDoctor,
   status: cmdStatus, report: cmdReport, dashboard: cmdDashboard, ui: cmdDashboard,
   lock: cmdLock, verify: cmdVerify, sessions: cmdSessions,
-  sources: cmdSources, watch: cmdWatch, team: cmdTeam,
+  sources: cmdSources, watch: cmdWatch, team: cmdTeam, join: cmdJoin,
   projects: cmdProjects, practices: cmdPractices, habits: cmdPractices, coach: cmdCoach,
   ledger: cmdLedger, export: cmdExport, rebuild: cmdRebuild, drain: cmdDrain,
   archive: cmdArchive, prune: cmdPrune, config: cmdConfig,
@@ -526,7 +528,17 @@ async function cmdDashboard(args) {
 
   if (loadConfig().dashboard.openOnStart && !args.includes('--no-open')) openUrl(url);
 
-  const stop = async () => { await close(); process.exit(0); };
+  // A second ctrl-c means "I do not believe you, leave now" — so the first
+  // press shuts down politely and the second one does not wait for it.
+  let stopping = false;
+  const stop = async () => {
+    if (stopping) process.exit(0);
+    stopping = true;
+    write();
+    write(grey('  stopping…'));
+    await close();
+    process.exit(0);
+  };
   process.on('SIGINT', stop);
   process.on('SIGTERM', stop);
 }
@@ -592,6 +604,130 @@ async function cmdWatch(args) {
   process.on('SIGINT', () => { clearInterval(timer); write(); process.exit(0); });
 }
 
+/**
+ * `syndes join <invite>` — everything a newcomer has to do, in one command.
+ *
+ * The person receiving an invite has not read any of this and should not have
+ * to. So this installs if it is not installed, works out why git cannot reach
+ * the repository, offers to fix that, joins, and publishes — reporting each
+ * step rather than failing with one line about credentials.
+ */
+async function cmdJoin(args) {
+  const raw = args.find((arg) => !arg.startsWith('--'));
+  if (!raw) throw new Error('usage: syndes join <invite-code>   (the line whoever invited you sent)');
+
+  const invite = decodeInvite(raw);
+  if (!invite) {
+    throw new Error('that does not look like an invite — paste the whole line you were sent, or use: syndes team join <repo-url>');
+  }
+
+  banner();
+  write(`  Joining ${bold(invite.pool ?? 'the pool')}${invite.from ? grey(`, invited by ${invite.from}`) : ''}`);
+  write(grey(`  ${invite.repo}`));
+  write();
+
+  if (!isInstalledHere()) {
+    const step = spinner('Setting up SynDes on this machine');
+    await beat();
+    await install({});
+    step.succeed(displayPath(installDir));
+  } else {
+    write(`  ${grey(DOT)} ${grey('already installed')}`);
+  }
+
+  if (!(await ensureReachable(invite.repo, args))) return;
+
+  let who = args.find((arg) => arg.startsWith('--name='))?.split('=').slice(1).join('=');
+  if (!who && process.stdin.isTTY) {
+    write();
+    who = (await ask(`  Your name, as the others will see it [${identity().name}]: `)).trim();
+  }
+  if (who) setName(who);
+
+  write();
+  const step = spinner('Joining the pool');
+  await beat();
+  try {
+    joinPool({ transport: invite.transport, repo: invite.repo });
+  } catch (error) {
+    step.fail(error.message);
+    process.exitCode = 1;
+    return;
+  }
+  step.succeed(poolName());
+
+  const share = spinner('Publishing this machine');
+  await beat();
+  const state = syncOnce();
+  if (state.ok) share.succeed(`${state.published} day(s) shared as ${identity().name}`);
+  else share.fail(state.error ?? 'could not publish');
+
+  const others = readPool().filter((peer) => !peer.isMe);
+  write();
+  write(`  ${OK} you are in${others.length ? grey(` · also here: ${others.map((peer) => peer.name).join(', ')}`) : ''}`);
+  write(grey(`  ${cyan('syndes dashboard')} then open Team`));
+  write();
+}
+
+function isInstalledHere() {
+  try {
+    return (adapterFor('claude-code').status?.().wired ?? 0) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check git can reach the repository, and fix it if we can.
+ *
+ * The confusing case this exists for: accepting a collaborator invite in a
+ * browser authorises the ACCOUNT, while git on this machine still cannot prove
+ * who it is — and GitHub answers that with "not found" rather than "not you".
+ */
+async function ensureReachable(repo, args = []) {
+  const step = spinner('Checking access to the repository');
+  await beat();
+  let report = preflight(repo);
+
+  if (report.ok) {
+    // Only claim an account when a reach check actually ran and passed with it.
+    // A folder pool, or a local path, never touches GitHub — saying "as <user>"
+    // there would credit an authentication that was not tested.
+    const tested = report.checks.some((check) => check.name === 'repository' && check.ok);
+    step.succeed(tested && report.gh.account ? `as ${report.gh.account}` : tested ? 'reachable' : 'no sign-in needed');
+    return true;
+  }
+  step.fail(report.blocking.detail);
+
+  if (report.gh.installed && process.stdin.isTTY && !args.includes('--no-fix')) {
+    write();
+    write(grey('  This is usually a sign-in, not a missing repository.'));
+    if (await confirm('  Sign in to GitHub now?', true)) {
+      write();
+      const fixed = repairAuth({ interactive: true });
+      write();
+      if (fixed.ran.length) write(grey(`  ran: ${fixed.ran.join(', ')}`));
+      const retry = spinner('Checking access again');
+      await beat();
+      report = preflight(repo);
+      if (report.ok) {
+        retry.succeed(report.gh.account ? `as ${report.gh.account}` : 'reachable');
+        return true;
+      }
+
+      retry.fail(report.blocking.detail);
+    }
+  }
+
+  write();
+  write(`  ${cyan('→')} ${report.blocking.fix}`);
+  if (!report.gh.installed) write(`  ${cyan('→')} the GitHub CLI makes this one command: ${ghInstallHint()}`);
+  write(grey('  then run this again — nothing is lost, recording has already started'));
+  write();
+  process.exitCode = 1;
+  return false;
+}
+
 /**
  * `syndes team …` — the shared-account pool.
  *
@@ -659,6 +795,63 @@ async function cmdTeam(args) {
     return;
   }
 
+  if (verb === 'invite') {
+    if (!isEnabled()) throw new Error('sharing is off — syndes team join <repo> first');
+    const code = inviteCode();
+    write();
+    write(`  ${bold('Send this line')} ${grey('· they paste it into a terminal, and that is all')}`);
+    write();
+    write(`  ${cyan(commandFor(code))}`);
+    write();
+    write(grey('  It installs SynDes, checks their GitHub access, offers to fix it,'));
+    write(grey('  and joins them to this pool.'));
+    write();
+    write(grey(`  ${WARN} first add them as a collaborator on ${teamConfig().repo}`));
+    write(grey('  The invite is not a key — access is the repository\'s collaborator list.'));
+    write(grey('  Everyone in the pool can see everyone else in it.'));
+    write();
+    return;
+  }
+
+  if (verb === 'remove') {
+    const target = rest.filter((arg) => !arg.startsWith('--')).join(' ');
+    if (!target) throw new Error('usage: syndes team remove <name>');
+    if (!isEnabled()) throw new Error('sharing is off');
+
+    const peers = readPool();
+    const match = peers.find((p) => p.deviceId === target || p.name?.toLowerCase() === target.toLowerCase());
+    if (!match) throw new Error(`no machine called "${target}" — ${peers.map((p) => p.name).join(', ')}`);
+
+    write();
+    write(`  ${WARN} removing ${bold(match.name)} takes their ${match.rollups.size} published day(s) out of the pool`);
+    write(grey('  Their own ledger is untouched. Past totals will change for everyone.'));
+    write(grey('  Git keeps the old commits, so this removes them from view, not from history.'));
+    write(grey(`  To stop them adding more, remove their GitHub access as well.`));
+    write();
+    if (process.stdin.isTTY && !rest.includes('--yes') && !(await confirm(`  Remove ${match.name}?`))) return write('cancelled');
+
+    const step = spinner(`Removing ${match.name}`);
+    await beat();
+    const result = removeDevice(match.deviceId);
+    if (!result.removed) { step.fail(result.error); process.exitCode = 1; return; }
+    if (result.pushed) step.succeed('removed and pushed');
+    else step.fail(`removed locally, but the push failed: ${result.error ?? 'unknown'}`);
+    return;
+  }
+
+  if (verb === 'doctor') {
+    const report = preflight(teamConfig().repo ?? null);
+    write();
+    for (const check of report.checks) {
+      const mark = check.ok === true ? OK : check.ok === false ? FAIL : grey(DOT);
+      write(`  ${mark} ${check.name.padEnd(12)} ${check.ok === false ? check.detail : grey(check.detail)}`);
+      if (check.fix) write(`     ${cyan('→')} ${check.fix}`);
+    }
+    write();
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
   if (verb === 'sync') {
     if (!isEnabled()) return write(grey('sharing is off — syndes team join <repo>'));
     const spin = spinner('Exchanging with the pool');
@@ -706,6 +899,8 @@ async function cmdTeam(args) {
   write();
   write(`  ${grey('overlap')} ${percent(data.grid.overlapRate)} ${grey(`of working hours had more than one of you in them`)}`);
   write();
+  write(grey(`  ${cyan('syndes team invite')} to add someone  ${DOT}  ${cyan('syndes team remove <name>')}  ${DOT}  ${cyan('syndes team doctor')}`));
+  write();
 }
 
 /** `syndes lock [open|system|pin]` */
@@ -801,7 +996,9 @@ function usage_() {
     [cyan('export --format=csv'), 'all of it, back out'],
     [cyan('sources'), 'which coding agents SynDes can see'],
     [cyan('watch [--once]'), 'follow agents that have no hook API'],
-    [cyan('team [join|status]'), 'share one account and see the split'],
+    [cyan('join <invite>'), 'accept an invite — installs and sets everything up'],
+    [cyan('team invite'), 'a line to send someone so they can join'],
+    [cyan('team [status|remove]'), 'share one account and see the split'],
     [cyan('lock [mode]'), 'how the dashboard unlocks: open, system or pin'],
     [cyan('doctor [--full]'), 'what is wired and what actually works'],
     [cyan('off [30m] / on'), 'pause and resume tracking'],

package/dashboard/api/team.mjs

@@ -15,7 +15,9 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { join } from 'node:path';
 import { team } from '../../analytics/team.mjs';
-import { joinPool, leave, publish, isEnabled, teamConfig } from '../../sync/index.mjs';
+import { joinPool, leave, publish, isEnabled, teamConfig, inviteCode, removeDevice, poolName } from '../../sync/index.mjs';
+import { commandFor } from '../../sync/invite.mjs';
+import { diagnose as preflight } from '../../src/preflight.mjs';
 import { setName } from '../../runtime/identity.mjs';
 import { rawConfig, saveConfig, setPath, resetCache } from '../../runtime/config.mjs';
 import { packageRoot } from '../../runtime/paths.mjs';
@@ -97,6 +99,32 @@ export async function teamAction({ body }) {
       return { data: { ok: true, pollSeconds: seconds } };
     }
 
+    if (action === 'invite') {
+      const code = inviteCode();
+      return {
+        data: {
+          ok: true,
+          code,
+          command: commandFor(code),
+          pool: poolName(),
+          repo: teamConfig().repo,
+        },
+      };
+    }
+
+    if (action === 'remove') {
+      // Removing someone is the one write outside our own shelf, so it is
+      // deliberately a separate action from anything the sync loop performs.
+      const result = removeDevice(String(body.deviceId ?? body.name ?? ''));
+      if (!result.removed) return { status: 400, data: { error: result.error ?? 'could not remove' } };
+      await syncNow();
+      return { data: { ok: true, name: result.name, pushed: result.pushed, error: result.error } };
+    }
+
+    if (action === 'check') {
+      return { data: preflight(teamConfig().repo ?? null) };
+    }
+
     if (action === 'sync') {
       const state = await syncNow();
       return { data: { ok: true, sync: state } };

package/dashboard/auth.mjs

@@ -32,6 +32,21 @@ export const MODES = ['open', 'system', 'pin'];
 /** Lives only in this process: a launch token dies with the server that made it. */
 let launchToken = null;
 
+/**
+ * This run of the server.
+ *
+ * A lock means "ask me", and the answer has to be asked again each time the
+ * dashboard starts. Without this the session cookie was checked only against
+ * auth.json, which survives a restart — so turning on Touch ID or a PIN asked
+ * once, and for the next twelve hours anybody who opened the dashboard walked
+ * straight in. The lock looked set and was not enforced, which is worse than no
+ * lock, because the user believes it.
+ *
+ * Bound only in `system` and `pin` modes. `open` has no lock to enforce and a
+ * session that outlives the process there is a convenience, not a bypass.
+ */
+let instance = randomBytes(9).toString('base64url');
+
 // ── Stored state ───────────────────────────────────────────────────────────
 
 export function loadAuth() {
@@ -174,6 +189,8 @@ export function systemAvailable() {
 export function issueToken(now = Date.now()) {
   const auth = ensureAuth();
   const payload = { exp: now + SESSION_MS, epoch: auth.sessionEpoch ?? 0, nonce: randomBytes(9).toString('base64url') };
+  // Stamp the run that issued it, so a restart asks again.
+  if ((auth.mode ?? 'open') !== 'open') payload.inst = instance;
   const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
   return `${body}.${sign(body, auth.secret)}`;
 }
@@ -195,6 +212,12 @@ export function verifyToken(token) {
 
   if (Date.now() > (payload.exp ?? 0)) return { ok: false, reason: 'expired' };
   if ((payload.epoch ?? -1) !== (auth.sessionEpoch ?? 0)) return { ok: false, reason: 'revoked' };
+
+  // Under a lock, a session belongs to the run that issued it. A cookie from a
+  // previous run — or one minted while the door was open — does not get in.
+  if ((auth.mode ?? 'open') !== 'open' && payload.inst !== instance) {
+    return { ok: false, reason: 'the dashboard was restarted' };
+  }
   return { ok: true, reason: null };
 }
 
@@ -232,4 +255,16 @@ function safeEqual(a, b) {
   return timingSafeEqual(Buffer.from(a), Buffer.from(b));
 }
 
+/**
+ * Forget every session this run issued, as a restart would.
+ *
+ * Exists for the tests: a restart is otherwise only reproducible by spawning a
+ * process, and the property being checked — that a lock is re-asked — deserves
+ * a direct test as well as an end-to-end one.
+ */
+export function resetInstance() {
+  instance = randomBytes(9).toString('base64url');
+  return instance;
+}
+
 export { SESSION_MS, ensureAuth };

package/dashboard/server.mjs

@@ -42,6 +42,19 @@ export async function startServer({ port, idleTimeoutMinutes } = {}) {
     send(res, 500, { error: 'internal error' });
   }); });
 
+  // Every open socket, so shutdown can hang them up.
+  //
+  // server.close() stops accepting new connections and then waits for the
+  // existing ones to finish — which for a browser keep-alive is "eventually"
+  // and for an event stream is "never". Without this, ctrl-c printed ^C and
+  // hung, and every further press queued another close callback until Node
+  // warned about a listener leak at eleven.
+  const sockets = new Set();
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
+
   let idleTimer = null;
   const touch = () => {
     if (!idleMs) return;
@@ -68,13 +81,36 @@ export async function startServer({ port, idleTimeoutMinutes } = {}) {
   const token = mintLaunchToken();
   const base = `http://${HOST}:${server.address().port}`;
   const url = authMode() === 'open' ? `${base}/?t=${token}` : base;
-  return {
-    url,
-    base,
-    port: server.address().port,
-    server,
-    close: () => new Promise((resolve) => { clearTimeout(idleTimer); server.close(resolve); }),
+
+  /**
+   * Stop listening and hang up.
+   *
+   * Idempotent: calling it twice must not register a second close callback,
+   * because the thing that calls it twice is somebody pressing ctrl-c again
+   * when the first press appeared to do nothing.
+   */
+  let closing = null;
+  const close = () => {
+    if (closing) return closing;
+    closing = new Promise((resolve) => {
+      clearTimeout(idleTimer);
+      let done = false;
+      const finish = () => { if (!done) { done = true; resolve(); } };
+
+      server.close(finish);
+      // Then end what is already open, oldest first — an event stream and a
+      // keep-alive both sit here forever otherwise.
+      for (const socket of sockets) socket.destroy();
+      sockets.clear();
+
+      // A socket wedged in a kernel buffer must not hold the process open.
+      const failsafe = setTimeout(finish, 2000);
+      failsafe.unref?.();
+    });
+    return closing;
   };
+
+  return { url, base, port: server.address().port, server, close, sockets };
 }
 
 async function handle(req, res, port) {

package/dashboard/web/api.js

@@ -72,6 +72,8 @@ export const api = {
 
   team: (range) => get(`/api/team?range=${encodeURIComponent(range)}`),
   teamAction: (action, payload = {}) => post('/api/team', { action, ...payload }),
+  teamInvite: () => post('/api/team', { action: 'invite' }),
+  teamRemove: (deviceId) => post('/api/team', { action: 'remove', deviceId }),
   // Not fetched through request(): an event stream is a live connection, not a
   // response with a body, so the view owns it and closes it itself.
   teamStreamUrl: (range) => `/api/team/stream?range=${encodeURIComponent(range)}`,

package/dashboard/web/app.css

@@ -540,6 +540,72 @@ a { color: inherit; text-decoration: none; }
 .field::placeholder { color: var(--ink-3); }
 .field:focus-visible { outline: 2px solid var(--lime); outline-offset: 2px; }
 
+/* A grid that reflows on available width rather than on a breakpoint. Cards
+   claim a column while one fits and wrap when it does not, so the same markup
+   suits a laptop and a wide monitor without a media query choosing for it. */
+.autogrid {
+  display: grid;
+  gap: var(--s5);
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  align-items: stretch;
+}
+.autogrid--wide { grid-template-columns: repeat(auto-fit, minmax(420px, 1fr)); }
+.team { align-content: start; }
+
+/* ── People ───────────────────────────────────────────────────────────── */
+
+/* Rows, not a table. Stacking within a person rather than across them is what
+   lets a narrow card drop a line instead of truncating a name. */
+.people { display: grid; }
+.person {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  gap: var(--s3);
+  align-items: start;
+  padding: var(--s4) 0;
+  border-top: 1px solid var(--line);
+}
+.person:first-child { padding-top: var(--s2); border-top: 0; }
+.person > .avatar { margin-top: 2px; }
+
+.person__head { display: flex; align-items: center; gap: var(--s2); flex-wrap: wrap; }
+.person__name {
+  font-weight: 650;
+  min-width: 0;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.person__tag { font-size: 11px; color: var(--ink-3); }
+/* Pushed right, and never wrapped away from the name it belongs to. */
+.person__share { margin-left: auto; font-size: 13px; font-weight: 700; font-variant-numeric: tabular-nums; }
+
+.person__stats { display: flex; flex-wrap: wrap; gap: 2px var(--s4); font-size: 12px; color: var(--ink-3); }
+.person__stat b { color: var(--ink); font-weight: 650; font-variant-numeric: tabular-nums; }
+
+@media (max-width: 520px) {
+  /* Below this the remove control cannot sit beside the row without squeezing
+     the name, so it moves under it rather than off the edge. */
+  .person { grid-template-columns: auto minmax(0, 1fr); }
+  .person > .btn { grid-column: 2; justify-self: start; }
+}
+
+/* The invite line. Monospace and selectable — somebody will always copy it by
+   hand rather than trust the button, and a wrapped command must still be one
+   correct command when it is pasted. */
+.invite {
+  display: block;
+  font-family: var(--mono);
+  font-size: 11px;
+  line-height: 1.6;
+  color: var(--lime);
+  background: var(--surface-3);
+  border-radius: var(--r-chip);
+  padding: var(--s3) var(--s4);
+  word-break: break-all;
+  user-select: all;
+  max-height: 140px;
+  overflow-y: auto;
+}
+
 /* ── Responsive ───────────────────────────────────────────────────────── */
 
 @media (max-width: 1240px) {

package/dashboard/web/ui.js

@@ -344,6 +344,7 @@ export function modal({
   title,
   note = null,
   input = null,       // { placeholder, type, inputmode, maxlength, validate }
+  body = null,        // extra nodes, rendered above the field
   confirmLabel = 'Confirm',
   cancelLabel = 'Cancel',
   danger = false,
@@ -376,6 +377,7 @@ export function modal({
     const panel = h('div.modal', { role: 'dialog', 'aria-modal': 'true', 'aria-label': title }, [
       h('div.modal__title', { text: title }),
       note ? h('div.modal__note', { text: note }) : null,
+      ...[].concat(body ?? []).filter(Boolean),
       field,
       field ? error : null,
       h('div.modal__actions', {}, [

package/dashboard/web/views/team.js

@@ -6,7 +6,7 @@
  *   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
+ *   4. How did each day break down?  the daily split, and who is in the pool
  *
  * 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
@@ -16,7 +16,7 @@
 
 import { api } from '../api.js';
 import {
-  h, card, figure, trend, chip, dot, meter, legend, empty, table, modal,
+  h, card, figure, trend, chip, dot, meter, legend, empty, modal,
   compact, usd, duration, percent, when, DASH,
 } from '../ui.js';
 import { dotMatrix, laneSplit, splitBar } from '../charts.js';
@@ -24,13 +24,14 @@ 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',
-  });
+  // Not `content--fit`. That pins the page to the viewport and divides what is
+  // left between two rows, which is right for a dense screen and wrong here:
+  // with one person in the pool the cards have little in them, and forcing them
+  // to fill a tall window leaves most of it empty. Letting the page size to its
+  // content and scroll adapts to any window instead of assuming one.
+  const outlet = h('div.content.team', {});
 
   if (!data.enabled) {
-    outlet.style.display = 'grid';
-    outlet.style.gridTemplateRows = 'minmax(0,1fr)';
     outlet.appendChild(setup(range, outlet));
     return outlet;
   }
@@ -79,12 +80,12 @@ function connect(outlet, range) {
 function paint(outlet, data, range, { live = false } = {}) {
   const me = data.peers.find((peer) => peer.isMe) ?? null;
 
+  // One auto-fitting grid rather than two fixed rows. Cards claim a column when
+  // there is room for one and wrap when there is not, so the same markup works
+  // on a laptop and on a wide monitor without a breakpoint deciding for it.
   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),
-    ]),
+    h('div.autogrid', {}, [shareCard(data, me), poolCard(data, live), contentionCard(data)]),
+    h('div.autogrid.autogrid--wide', {}, [splitCard(data), peopleCard(data, outlet, range)]),
   );
 }
 
@@ -106,9 +107,13 @@ function shareCard(data, me) {
         }) : null,
       }),
       h('div', { style: 'display:grid;gap:4px' }, [
-        h('span.card__note', { text: `Even split would be ${percent(fair)}` }),
+        // Meaningless while you are the only one here — "an even split would be
+        // 100%" is true and says nothing.
+        data.peers.length > 1 ? h('span.card__note', { text: `Even split would be ${percent(fair)}` }) : null,
         h('span.card__note', {
-          text: `${compact(me?.totals.tokens ?? 0)} of ${compact(data.totals.tokens)} tokens`,
+          text: data.peers.length > 1
+            ? `${compact(me?.totals.tokens ?? 0)} of ${compact(data.totals.tokens)} tokens`
+            : `${compact(data.totals.tokens)} tokens · nobody else has joined yet`,
         }),
       ]),
     ]),
@@ -169,7 +174,9 @@ function contentionCard(data) {
   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'),
+      overlapping
+        ? chip(`${grid.overlapBands} band${grid.overlapBands === 1 ? '' : 's'}`, 'orange')
+        : chip('no overlap', 'lime'),
     ]),
     dotMatrix(grid),
     legend([
@@ -201,52 +208,164 @@ function splitCard(data) {
 }
 
 // 4b. The people
+/**
+ * One block per person, not a table.
+ *
+ * This was a seven-column table, and it did not survive contact with a real
+ * card: the name truncated to "Gurupra…", "3h 21m" wrapped and clipped, and the
+ * remove control was pushed off the right edge behind a scrollbar. A table needs
+ * a width it can rely on, and a card in a reflowing grid cannot promise one.
+ *
+ * Rows fix that by stacking within each person rather than across them — the
+ * name gets the width, the numbers wrap as a group, and nothing is ever cut off.
+ */
 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,
+  const actions = h('div', { style: 'display:flex;gap:8px;flex-wrap:wrap' }, [
+    h('button.btn.btn--lime.btn--sm', { text: 'Invite', onclick: () => invite() }),
+    h('button.btn.btn--ghost.btn--sm', { text: 'Rename', onclick: () => rename(data, outlet, range) }),
+    h('button.btn.btn--ghost.btn--sm', { text: 'Sync now', onclick: () => syncNow(outlet, range) }),
+  ]);
+
+  return card('People', [
+    h('div.people', {}, data.peers.map((peer) => personRow(peer, outlet, range))),
+
+    data.peers.length === 1
+      ? h('span.card__note', { text: 'Only this machine so far. Invite gives you a line to send someone.' })
+      : h('span.card__note', { text: 'A stale shelf has not synced in six hours — a machine that stopped reporting, not a quiet day.' }),
+
+    h('div', { style: 'margin-top:auto;display:flex;gap:8px;flex-wrap:wrap;padding-top:var(--s2)' }, [
+      h('button.btn.btn--ghost.btn--sm', { text: `Sharing: ${data.config.scope}`, onclick: () => changeScope(data, outlet, range) }),
+      h('button.btn.btn--ghost.btn--sm', { text: 'Leave pool', onclick: () => leavePool(outlet, range) }),
     ]),
-    h('div', { style: 'display:grid;gap:5px;min-width:90px' }, [
-      h('span.tnum', { style: 'font-size:12px', text: percent(peer.share) }),
+  ], { actions });
+}
+
+function personRow(peer, outlet, range) {
+  return h('div.person', {}, [
+    h('span.avatar', { text: peer.initials, title: peer.host ?? peer.deviceId }),
+
+    h('div', { style: 'min-width:0;display:grid;gap:6px' }, [
+      h('div.person__head', {}, [
+        h('span.person__name', { text: peer.name, title: peer.name }),
+        peer.isMe ? h('span.person__tag', { text: 'this machine' }) : null,
+        peer.stale ? chip('stale', 'orange') : null,
+        h('span.person__share', { text: percent(peer.share) }),
+      ]),
+
       meter(peer.share, peer.isMe ? 'lime' : 'white'),
+
+      // Wraps as a group rather than being squeezed into columns, so a narrow
+      // card loses a line instead of losing a number.
+      h('div.person__stats', {}, [
+        stat(compact(peer.totals.tokens), 'tokens'),
+        stat(String(peer.totals.sessions), peer.totals.sessions === 1 ? 'session' : 'sessions'),
+        stat(duration(peer.totals.activeMs), 'active'),
+        stat(peer.score === null ? DASH : String(peer.score), 'score'),
+      ]),
     ]),
-    compact(peer.totals.tokens),
-    String(peer.totals.sessions),
-    duration(peer.totals.activeMs),
-    peer.score === null ? DASH : String(peer.score),
-  ]);
 
-  const actions = h('div', { style: 'display:flex;gap:8px' }, [
-    h('button.btn.btn--ghost', { text: 'Rename', onclick: () => rename(data, outlet, range) }),
-    h('button.btn.btn--ghost', { text: 'Sync now', onclick: () => syncNow(outlet, range) }),
+    peer.isMe
+      ? null
+      : h('button.btn.btn--ghost.btn--sm', {
+          text: 'Remove',
+          title: `Remove ${peer.name} from the pool`,
+          onclick: () => remove(peer, outlet, range),
+        }),
   ]);
+}
 
-  return card('People', [
-    table(
-      ['Person', 'Share', 'Tokens', 'Sessions', 'Active', 'Score'],
-      rows,
-      { align: ['left', 'left', '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 });
+function stat(value, label) {
+  return h('span.person__stat', {}, [h('b', { text: value }), h('span', { text: ` ${label}` })]);
 }
 
 // ── 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?',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndes",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "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",

package/src/preflight.mjs

@@ -0,0 +1,174 @@
+/**
+ * Can this machine actually reach the pool — and if not, what fixes it.
+ *
+ * Joining a shared repository fails for a handful of dull reasons that all
+ * surface as the same unhelpful git error, and one of them is genuinely
+ * confusing: accepting a collaborator invite in a browser grants the ACCOUNT
+ * access, while git on the machine still has no idea who you are. GitHub then
+ * returns 404 rather than admit a private repository exists, so the honest
+ * message "you are not signed in" arrives disguised as "no such repo".
+ *
+ * So every check here answers three things: what was tested, what happened, and
+ * the exact next command. A check that cannot answer returns `null` rather than
+ * guessing — same rule the platform probes follow.
+ *
+ * Nothing is installed without being asked. Software installs itself on a
+ * developer's machine only when they say so; the most this does unattended is
+ * teach git to use credentials the user already has.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { which, isMac, isWindows, platformName } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const TIMEOUT_MS = 20_000;
+
+function run(binary, args, { timeout = TIMEOUT_MS, quiet = true } = {}) {
+  try {
+    const out = execFileSync(binary, args, {
+      encoding: 'utf8',
+      timeout,
+      stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo' },
+    });
+    return { ok: true, out: (out ?? '').trim(), error: null };
+  } catch (error) {
+    const stderr = String(error.stderr ?? '').trim();
+    return { ok: false, out: '', error: (stderr || error.message).split('\n').slice(-2).join(' ').slice(0, 240) };
+  }
+}
+
+/** How this platform installs the GitHub CLI. */
+export function ghInstallHint() {
+  if (isMac) return which('brew') ? 'brew install gh' : 'see https://cli.github.com (or: brew install gh)';
+  if (isWindows) return 'winget install --id GitHub.cli';
+  return 'see https://cli.github.com — most distros package it as `gh`';
+}
+
+export function gitInstallHint() {
+  if (isMac) return 'xcode-select --install';
+  if (isWindows) return 'winget install --id Git.Git';
+  return 'your package manager, e.g. apt install git';
+}
+
+/** @returns {{installed: boolean, authed: boolean, account: string|null, gitConfigured: boolean}} */
+export function ghState() {
+  const gh = which('gh');
+  if (!gh) return { installed: false, authed: false, account: null, gitConfigured: false };
+
+  const status = run(gh, ['auth', 'status']);
+  const account = /Logged in to \S+ account (\S+)/.exec(`${status.out}\n${status.error ?? ''}`)?.[1] ?? null;
+
+  // `gh auth setup-git` writes a credential helper entry; without it a gh login
+  // authenticates the gh command and nothing else, which is the trap.
+  const helper = run(which('git') ?? 'git', ['config', '--get-regexp', 'credential.*helper']);
+  return {
+    installed: true,
+    authed: Boolean(account),
+    account,
+    gitConfigured: /gh auth git-credential|gh\b/.test(helper.out),
+  };
+}
+
+/**
+ * Everything that must be true before a join can work.
+ *
+ * @param {string|null} repo  the remote to test, or null to skip the reach check
+ * @returns {{ok: boolean, checks: object[], blocking: object|null}}
+ */
+export function diagnose(repo = null) {
+  const checks = [];
+  const git = which('git');
+
+  checks.push(git
+    ? { name: 'git', ok: true, detail: git }
+    : { name: 'git', ok: false, detail: `not installed on this ${platformName}`, fix: gitInstallHint() });
+
+  const gh = ghState();
+  checks.push(gh.installed
+    ? { name: 'gh', ok: true, detail: gh.authed ? `signed in as ${gh.account}` : 'installed, not signed in' }
+    : { name: 'gh', ok: null, detail: 'not installed — optional, but it is the easiest way to authenticate', fix: ghInstallHint() });
+
+  if (git && repo && !repo.startsWith('/') && !repo.startsWith('~')) {
+    const reach = run(git, ['ls-remote', '--heads', repo]);
+    if (reach.ok) {
+      checks.push({ name: 'repository', ok: true, detail: 'reachable, and git can authenticate' });
+    } else {
+      checks.push({
+        name: 'repository',
+        ok: false,
+        detail: explain(reach.error, gh),
+        fix: remedy(gh, repo),
+        raw: reach.error,
+      });
+    }
+  }
+
+  const blocking = checks.find((check) => check.ok === false) ?? null;
+  return { ok: !blocking, checks, blocking, gh };
+}
+
+/**
+ * Turn git's message into the actual problem.
+ *
+ * "Repository not found" on a private repo almost never means the repo is
+ * missing — it means GitHub will not confirm it exists to someone it cannot
+ * identify. Repeating git's wording would send the user to check the URL, which
+ * is the one thing that is usually right.
+ */
+function explain(error, gh) {
+  const text = String(error ?? '');
+  if (/could not read Username|Authentication failed|terminal prompts disabled/i.test(text)) {
+    return gh.authed
+      ? `git has no credentials for this remote, though gh is signed in as ${gh.account}`
+      : 'git has no credentials for this remote';
+  }
+  if (/not found|does not exist/i.test(text)) {
+    return gh.authed
+      ? `not visible to ${gh.account} — either the invite is not accepted, or git is not using that account`
+      : 'private repositories are invisible until git can prove who you are';
+  }
+  if (/Permission denied \(publickey\)/i.test(text)) return 'no SSH key on this machine that GitHub recognises';
+  if (/Could not resolve host|network/i.test(text)) return 'cannot reach the network';
+  return text.slice(0, 160);
+}
+
+function remedy(gh, repo) {
+  const ssh = repo.startsWith('git@') || repo.startsWith('ssh://');
+  if (ssh) return 'add an SSH key to your GitHub account, or use the https:// url instead';
+  if (!gh.installed) return `${ghInstallHint()}, then: gh auth login && gh auth setup-git`;
+  if (!gh.authed) return 'gh auth login';
+  if (!gh.gitConfigured) return 'gh auth setup-git';
+  return 'check the collaborator invite has been accepted for this account';
+}
+
+/**
+ * Fix what can be fixed without installing anything.
+ *
+ * `gh auth login` is interactive by design — it opens a browser and asks the
+ * person to confirm — so it is only attempted when there is a terminal to run
+ * it in, and it inherits stdio so the user sees and answers it themselves.
+ *
+ * @returns {{ran: string[], ok: boolean}}
+ */
+export function repair({ interactive = Boolean(process.stdin.isTTY) } = {}) {
+  const gh = ghState();
+  const ran = [];
+  if (!gh.installed) return { ran, ok: false };
+
+  const binary = which('gh');
+  if (!gh.authed) {
+    if (!interactive) return { ran, ok: false };
+    ran.push('gh auth login');
+    const result = run(binary, ['auth', 'login'], { quiet: false, timeout: 300_000 });
+    if (!result.ok) return { ran, ok: false };
+  }
+
+  if (!ghState().gitConfigured) {
+    ran.push('gh auth setup-git');
+    const result = run(binary, ['auth', 'setup-git']);
+    if (!result.ok) { debug('gh auth setup-git failed', result.error); return { ran, ok: false }; }
+  }
+  return { ran, ok: ghState().authed };
+}

package/sync/index.mjs

@@ -25,9 +25,11 @@ import { identity } from '../runtime/identity.mjs';
 import { loadRollup, coveredDays } from '../analytics/rollup.mjs';
 import { localDay, shiftDay } from '../analytics/ranges.mjs';
 import { sanitise, manifestFor } from './share.mjs';
+import { encode as encodeInvite } from './invite.mjs';
 import {
-  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile,
+  transportFor, listDevices, readJsonFile, writeJsonFile, removeFile, git,
 } from './transport.mjs';
+import { rmSync } from 'node:fs';
 import { writeFileSync, renameSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { debug } from '../runtime/log.mjs';
@@ -192,6 +194,83 @@ export function readPool({ root = poolRoot(), days = null } = {}) {
   return peers;
 }
 
+/**
+ * An invite for this pool, for the owner to send.
+ *
+ * Carries the repository address and a label — never a credential. Who may join
+ * is decided by the repository's collaborator list, which is the only place that
+ * decision can be revoked from.
+ */
+export function inviteCode({ from = null } = {}) {
+  const team = teamConfig();
+  if (!team.enabled || !team.repo) throw new Error('sharing is off — join or create a pool first');
+  return encodeInvite({
+    repo: team.repo,
+    transport: team.transport ?? 'git',
+    pool: poolName(),
+    from: from ?? identity().name,
+  });
+}
+
+/** A readable label for the pool, taken from the repository name. */
+export function poolName() {
+  const repo = teamConfig().repo ?? '';
+  const last = repo.replace(/\.git$/, '').split(/[/\\:]/).filter(Boolean).pop();
+  return last || 'pool';
+}
+
+/**
+ * Remove someone's shelf from the pool.
+ *
+ * This is the ONE operation that deliberately writes outside our own directory,
+ * and it is an explicit administrative act rather than part of any sync. Git
+ * permissions are per-repository, so anyone with write access could already do
+ * this by hand; having a command for it means it is done correctly — the folder
+ * removed, the change pushed — instead of half-done.
+ *
+ * It removes them from view, not from history. Earlier commits still hold the
+ * data and anyone who pulled before still has a copy. The caller is expected to
+ * have said so before calling this.
+ *
+ * @returns {{removed: boolean, name: string|null, pushed: boolean, error: string|null}}
+ */
+export function removeDevice(target, { push = true } = {}) {
+  const root = poolRoot();
+  const me = identity();
+
+  const peers = readPool({ root });
+  const match = peers.find((peer) => peer.deviceId === target)
+    ?? peers.find((peer) => peer.name?.toLowerCase() === String(target).toLowerCase());
+
+  if (!match) return { removed: false, name: null, pushed: false, error: `no machine called "${target}" in the pool` };
+  if (match.deviceId === me.deviceId) {
+    // Deleting your own shelf while still publishing would simply re-create it
+    // on the next sync, which looks like the command silently failed.
+    return { removed: false, name: match.name, pushed: false, error: 'that is this machine — use `syndes team leave` instead' };
+  }
+
+  const shelf = teamDeviceDir(root, match.deviceId);
+  const relative = `devices/${match.deviceId}`;
+
+  if ((teamConfig().transport ?? 'git') !== 'git') {
+    try { rmSync(shelf, { recursive: true, force: true }); } catch (error) { return { removed: false, name: match.name, pushed: false, error: error.message }; }
+    return { removed: true, name: match.name, pushed: true, error: null };
+  }
+
+  const removed = git(root, ['rm', '-r', '--quiet', '--', relative]);
+  if (!removed.ok) return { removed: false, name: match.name, pushed: false, error: removed.error };
+
+  const committed = git(root, ['commit', '-m', `syndes: remove ${match.name} from the pool`, '--', relative]);
+  if (!committed.ok) return { removed: true, name: match.name, pushed: false, error: committed.error };
+
+  if (!push) return { removed: true, name: match.name, pushed: false, error: null };
+
+  const transport = transportFor('git');
+  transport.pull(root);
+  const pushed = git(root, ['push', 'origin', 'HEAD'], 25_000);
+  return { removed: true, name: match.name, pushed: pushed.ok, error: pushed.ok ? null : pushed.error };
+}
+
 // ── One cycle ───────────────────────────────────────────────────────────────
 
 /**

package/sync/invite.mjs

@@ -0,0 +1,70 @@
+/**
+ * Invites: one string that carries everything a new machine needs to join.
+ *
+ * The alternative is a paragraph of instructions — "install this, then run that,
+ * paste this URL, use your own GitHub" — which is where onboarding goes to die.
+ * An invite collapses it into a line the inviter copies and the joiner pastes.
+ *
+ * ── An invite is NOT a credential ──────────────────────────────────────────
+ * It carries a repository address and a label, nothing else. Access is decided
+ * entirely by whether GitHub lets that person in, which the repository owner
+ * controls with collaborator permissions and can revoke. Encoding a token here
+ * would mean the inviter's own credentials travelling through a chat app, which
+ * is exactly the practice this tool should not be teaching. So the invite is
+ * base64 for tidiness, not for secrecy, and it is safe to say so out loud.
+ */
+
+const PREFIX = 'syndes1_';
+const VERSION = 1;
+
+/**
+ * @param {{repo: string, transport: 'git'|'folder', pool?: string, from?: string}} details
+ * @returns {string}
+ */
+export function encode({ repo, transport = 'git', pool = null, from = null }) {
+  if (!repo) throw new Error('an invite needs a repository');
+  const body = { v: VERSION, r: repo, t: transport };
+  if (pool) body.p = pool.slice(0, 60);
+  if (from) body.f = from.slice(0, 40);
+  return PREFIX + Buffer.from(JSON.stringify(body), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode, tolerating what people actually paste — surrounding quotes, a stray
+ * backtick from a chat app, the whole command line rather than just the code.
+ *
+ * @returns {{repo, transport, pool, from}|null} null when it is not an invite
+ */
+export function decode(input) {
+  if (typeof input !== 'string') return null;
+
+  let text = input.trim().replace(/^[`'"]+|[`'"]+$/g, '');
+  const found = /syndes1_[A-Za-z0-9_-]+/.exec(text);
+  if (found) text = found[0];
+  if (!text.startsWith(PREFIX)) return null;
+
+  try {
+    const body = JSON.parse(Buffer.from(text.slice(PREFIX.length), 'base64url').toString('utf8'));
+    if (body.v !== VERSION || typeof body.r !== 'string' || !body.r) return null;
+    return {
+      repo: body.r,
+      transport: body.t === 'folder' ? 'folder' : 'git',
+      pool: typeof body.p === 'string' ? body.p : null,
+      from: typeof body.f === 'string' ? body.f : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The line an inviter sends. Two steps, because the install must be global. */
+export function commandFor(code) {
+  return `npm install -g syndes && syndes join ${code}`;
+}
+
+/** True for anything that looks like an invite, so `join` can accept a raw URL too. */
+export function looksLikeInvite(input) {
+  return typeof input === 'string' && input.includes(PREFIX);
+}
+
+export { PREFIX };