syndes 0.1.0 → 0.3.0

package/README.md

@@ -29,6 +29,13 @@ surface at most one nudge, at a moment that does not interrupt you, always with
 the evidence attached: *"you edited `src/app.ts` six times in twelve minutes
 without running tests."*
 
+**Splits one shared account between the people on it.** Two people on one Claude
+plan look like one user to Anthropic — there is no per-person breakdown to ask
+for. SynDes measures on each machine and pools the results through a private git
+repo or a synced folder, so you get the actual split: who used what, when, and
+which hours you spent competing for the same rate-limit window. Counts and
+tokens are shared; prompts, paths and commands never leave the machine.
+
 **Shows you the whole picture.** `syndes dashboard` opens a local
 dashboard: your efficiency score and its five pillars, token and cost
 breakdowns, cache hit rate, active time versus wall-clock, permission friction,
@@ -50,6 +57,8 @@ machine already has — `syndes lock system` asks Touch ID — or set a PIN.
 | `syndes sessions` | list and drill down |
 | `syndes export --format=csv` | all of it, back out |
 | `syndes lock system` | require Touch ID to open the dashboard |
+| `syndes team join <repo>` | share one account, see the split |
+| `syndes team status` | who used how much |
 | `syndes sources` | which coding agents SynDes can see |
 | `syndes watch` | follow agents that have no hook API |
 | `syndes doctor` | what is wired and what actually works |
@@ -66,6 +75,50 @@ request whose `Host` is not a literal loopback address — without that, any web
 page you have open could read it. The lock is the second layer, for machines
 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
+```
+
+**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.
+
+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
+and the only way a split can be enforced rather than agreed.
+
 ## Honest limits
 
 The ledger is **tamper-evident, not tamper-proof**. Anything running as your

package/analytics/metrics/rework.mjs

@@ -85,11 +85,17 @@ export function merge(parts) {
   let verifiedRuns = 0;
   let unverifiedRuns = 0;
 
+  // A storm's key names the command that failed, so it is never shared — but
+  // the COUNT is what the score reads, and without it a shared rollup scored a
+  // free hundred on the one part meant to catch a loop that is not converging.
+  let stormsCounted = 0;
+
   for (const part of parts) {
     for (const [path, count] of Object.entries(part.churn ?? {})) {
       churn[path] = Math.max(churn[path] ?? 0, count);
     }
-    storms.push(...(part.storms ?? []));
+    if (Array.isArray(part.storms)) storms.push(...part.storms);
+    else stormsCounted += part.stormCount ?? 0;
     errors += part.errors ?? 0;
     calls += part.calls ?? 0;
     verifiedRuns += part.verifiedRuns ?? 0;
@@ -102,7 +108,7 @@ export function merge(parts) {
     churn: Object.fromEntries(ranked.slice(0, 25)),
     worstChurn: ranked[0] ? { path: ranked[0][0], edits: ranked[0][1] } : null,
     storms: storms.slice(0, 25),
-    stormCount: storms.length,
+    stormCount: storms.length + stormsCounted,
     errors,
     calls,
     errorRate: calls ? errors / calls : 0,

package/analytics/metrics/volume.mjs

@@ -68,11 +68,24 @@ export function merge(parts) {
   const files = new Set();
   const totals = { prompts: 0, toolCalls: 0, writes: 0, commits: 0, insertions: 0, deletions: 0, filesChanged: 0 };
 
+  // A shared rollup has had its ids removed and carries only a count (see
+  // sync/share.mjs). Deduplication is impossible without the ids, so those
+  // counts are summed instead — which over-counts a session spanning midnight
+  // and is far better than the alternative, which was reporting zero sessions
+  // and silently dropping the largest part of the context score.
+  const counted = { sessions: 0, projects: 0, files: 0 };
+
   const bySource = {};
   for (const part of parts) {
-    for (const id of part.sessions ?? []) sessions.add(id);
-    for (const id of part.projects ?? []) projects.add(id);
-    for (const file of part.files ?? []) files.add(file);
+    if (Array.isArray(part.sessions)) for (const id of part.sessions) sessions.add(id);
+    else counted.sessions += part.sessionCount ?? 0;
+
+    if (Array.isArray(part.projects)) for (const id of part.projects) projects.add(id);
+    else counted.projects += part.projectCount ?? 0;
+
+    if (Array.isArray(part.files)) for (const file of part.files) files.add(file);
+    else counted.files += part.fileCount ?? 0;
+
     for (const key of Object.keys(totals)) totals[key] += part[key] ?? 0;
 
     for (const [id, bucket] of Object.entries(part.bySource ?? {})) {
@@ -86,9 +99,9 @@ export function merge(parts) {
 
   return {
     ...totals,
-    sessionCount: sessions.size,
-    projectCount: projects.size,
-    fileCount: files.size,
+    sessionCount: sessions.size + counted.sessions,
+    projectCount: projects.size + counted.projects,
+    fileCount: files.size + counted.files,
     sessions: [...sessions],
     projects: [...projects],
     bySource: Object.fromEntries(Object.entries(bySource).map(([id, b]) => [id, {

package/analytics/team.mjs

@@ -0,0 +1,245 @@
+/**
+ * The shared-account view: who used how much, and when you were in each
+ * other's way.
+ *
+ * The headline number here is deliberately NOT dollars. On a shared plan there
+ * is no per-token bill to split — the scarce thing is the usage window, and two
+ * people working the same hour throttle each other in a way neither of them can
+ * see from their own machine. So this module computes share, and it computes
+ * contention, and it treats cost as the secondary figure it actually is.
+ *
+ * Everything is derived from sanitised peer rollups (sync/share.mjs), which
+ * carry counts and no content. Nothing here reads a peer's records, because
+ * nothing ever sends them.
+ */
+
+import { rangeFor, previousRange } from './ranges.mjs';
+import { mergeRollups, METRICS } from './rollup.mjs';
+import { costOf } from './metrics/cost.mjs';
+import { score } from './score.mjs';
+import { readPool, loadState, teamConfig, isEnabled, poolRoot } from '../sync/index.mjs';
+import { identity, initialsOf } from '../runtime/identity.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+
+/** Three-hour bands: eight rows is a grid you can read, twenty-four is a wall. */
+const BAND_HOURS = 3;
+const BANDS = 24 / BAND_HOURS;
+/** Beyond this the grid stops being a picture and starts being a spreadsheet. */
+const MAX_GRID_DAYS = 14;
+
+/**
+ * @param {string} spec  a range spec, as analytics/ranges.mjs understands it
+ * @returns {Promise<object>} everything the Team page renders
+ */
+export async function team(spec = '7d') {
+  const range = rangeFor(spec);
+  const before = previousRange(range);
+  const prices = loadConfig().prices ?? {};
+  const me = identity();
+
+  const enabled = isEnabled();
+  const pool = enabled ? readPool() : [];
+
+  const peers = pool.map((peer) => {
+    const current = rollupsIn(peer, range.days);
+    const previous = rollupsIn(peer, before.days);
+
+    const merged = mergeRollups(current);
+    const mergedBefore = mergeRollups(previous);
+    const tokens = totalTokens(merged.tokens);
+
+    return {
+      deviceId: peer.deviceId,
+      name: peer.name,
+      initials: initialsOf(peer.name),
+      host: peer.host,
+      os: peer.os,
+      scope: peer.scope,
+      isMe: peer.isMe,
+      lastSeen: peer.lastSeen,
+      // A shelf nobody has updated in a day is stale, not quiet. The UI must be
+      // able to tell those apart or it will report someone as idle who has
+      // simply stopped syncing.
+      stale: peer.lastSeen ? Date.now() - peer.lastSeen > 6 * 3_600_000 : true,
+      days: current.length,
+      totals: {
+        tokens,
+        input: merged.tokens.input ?? 0,
+        output: merged.tokens.output ?? 0,
+        cacheRead: merged.tokens.cacheRead ?? 0,
+        cacheWrite: merged.tokens.cacheWrite ?? 0,
+        cacheHitRate: merged.tokens.cacheHitRate ?? 0,
+        prompts: merged.prompts.count ?? 0,
+        toolCalls: merged.tools.calls ?? 0,
+        sessions: sessionCountOf(merged, current),
+        activeMs: merged.time.activeMs ?? 0,
+        wallMs: merged.time.wallMs ?? 0,
+        compacts: merged.context.compacts ?? 0,
+        blocks: merged.friction.blocks ?? 0,
+        usd: costOf(merged.tokens, prices).usd,
+      },
+      previousTokens: totalTokens(mergedBefore.tokens),
+      // A peer sharing at `summary` still has every pillar the score reads,
+      // because the score never needed a path or a session id.
+      score: score(merged).total,
+      hours: merged.time.hours ?? new Array(24).fill(0),
+      series: range.days.map((day) => {
+        const rollup = peer.rollups.get(day);
+        return {
+          day,
+          tokens: rollup ? totalTokens(mergeRollups([rollup]).tokens) : 0,
+          activeMs: rollup?.metrics?.time?.activeMs ?? 0,
+          prompts: rollup?.metrics?.prompts?.count ?? 0,
+          toolCalls: rollup?.metrics?.tools?.calls ?? 0,
+          hours: rollup?.metrics?.time?.hours ?? new Array(24).fill(0),
+        };
+      }),
+    };
+  });
+
+  const poolTokens = peers.reduce((sum, peer) => sum + peer.totals.tokens, 0);
+  const poolBefore = peers.reduce((sum, peer) => sum + peer.previousTokens, 0);
+
+  for (const peer of peers) {
+    peer.share = poolTokens ? peer.totals.tokens / poolTokens : 0;
+    const shareBefore = poolBefore ? peer.previousTokens / poolBefore : null;
+    peer.shareDelta = shareBefore === null ? null : peer.share - shareBefore;
+  }
+  peers.sort((a, b) => b.totals.tokens - a.totals.tokens);
+
+  return {
+    enabled,
+    config: {
+      transport: teamConfig().transport ?? null,
+      scope: teamConfig().scope ?? 'summary',
+      pollSeconds: teamConfig().pollSeconds ?? 30,
+      pool: enabled ? poolRoot() : null,
+    },
+    sync: loadState(),
+    me: { deviceId: me.deviceId, name: me.name, initials: initialsOf(me.name) },
+    range: { ...range, label: range.label },
+    peers,
+    totals: {
+      tokens: poolTokens,
+      usd: peers.reduce((sum, peer) => sum + peer.totals.usd, 0),
+      prompts: peers.reduce((sum, peer) => sum + peer.totals.prompts, 0),
+      toolCalls: peers.reduce((sum, peer) => sum + peer.totals.toolCalls, 0),
+      activeMs: peers.reduce((sum, peer) => sum + peer.totals.activeMs, 0),
+      sessions: peers.reduce((sum, peer) => sum + peer.totals.sessions, 0),
+      people: peers.length,
+      deltaTokens: poolBefore ? poolTokens - poolBefore : null,
+    },
+    grid: contentionGrid(peers, range.days),
+    lanes: laneRows(peers, range.days),
+  };
+}
+
+/**
+ * The contention grid — the one picture that answers "were we in each other's
+ * way".
+ *
+ * Each cell is a three-hour band of one day. Size carries volume; colour carries
+ * how many people were working in it, which on a shared plan is the thing that
+ * actually costs you: one person alone gets the whole window, two people split
+ * it and both get throttled. Colour is therefore load-bearing here in exactly
+ * the way the palette intends — orange means look at this, and it means it
+ * because that band is where your limits were being spent twice.
+ */
+function contentionGrid(peers, days) {
+  const window = days.slice(-MAX_GRID_DAYS);
+  const cells = [];
+  let peak = 0;
+
+  for (const day of window) {
+    for (let band = 0; band < BANDS; band += 1) {
+      const byDevice = {};
+      let total = 0;
+
+      for (const peer of peers) {
+        const entry = peer.series.find((point) => point.day === day);
+        if (!entry) continue;
+        let count = 0;
+        for (let hour = band * BAND_HOURS; hour < (band + 1) * BAND_HOURS; hour += 1) {
+          count += entry.hours[hour] ?? 0;
+        }
+        if (count > 0) byDevice[peer.deviceId] = count;
+        total += count;
+      }
+
+      peak = Math.max(peak, total);
+      cells.push({
+        day,
+        band,
+        hour: band * BAND_HOURS,
+        total,
+        people: Object.keys(byDevice).length,
+        byDevice,
+      });
+    }
+  }
+
+  const overlapping = cells.filter((cell) => cell.people > 1);
+  return {
+    days: window,
+    bands: BANDS,
+    bandHours: BAND_HOURS,
+    cells,
+    peak,
+    overlapBands: overlapping.length,
+    // Reported as a share of the bands that had ANY work in them. A share of all
+    // bands would be dominated by everyone being asleep, which flatters nobody.
+    overlapRate: cells.filter((cell) => cell.total > 0).length
+      ? overlapping.length / cells.filter((cell) => cell.total > 0).length
+      : 0,
+  };
+}
+
+/** One row per day, split into each person's segment — the split, day by day. */
+function laneRows(peers, days) {
+  return [...days].reverse().slice(0, 12).map((day) => {
+    const segments = peers
+      .map((peer) => {
+        const point = peer.series.find((entry) => entry.day === day);
+        return {
+          deviceId: peer.deviceId,
+          name: peer.name,
+          initials: peer.initials,
+          isMe: peer.isMe,
+          tokens: point?.tokens ?? 0,
+          activeMs: point?.activeMs ?? 0,
+        };
+      })
+      .filter((segment) => segment.tokens > 0)
+      .sort((a, b) => b.tokens - a.tokens);
+
+    return { day, total: segments.reduce((sum, s) => sum + s.tokens, 0), segments };
+  });
+}
+
+function rollupsIn(peer, days) {
+  const out = [];
+  for (const day of days) {
+    const rollup = peer.rollups.get(day);
+    if (rollup) out.push(rollup);
+  }
+  return out;
+}
+
+function totalTokens(summary) {
+  if (!summary) return 0;
+  return (summary.input ?? 0) + (summary.output ?? 0) + (summary.cacheRead ?? 0) + (summary.cacheWrite ?? 0);
+}
+
+/**
+ * Sessions, from whichever field the peer's scope left us.
+ *
+ * At `summary` the ids are gone and only a count survives, so summing the
+ * per-day counts is the honest answer — it over-counts a session that spans
+ * midnight, which is a smaller error than reporting zero.
+ */
+function sessionCountOf(merged, rollups) {
+  if (merged.volume?.sessionCount) return merged.volume.sessionCount;
+  return rollups.reduce((sum, rollup) => sum + (rollup.metrics?.volume?.sessionCount ?? 0), 0);
+}
+
+export { contentionGrid, BAND_HOURS, BANDS };