clay-server 4.0.0-beta.8 → 4.0.0

package/lib/capsule-pig-logic.js

@@ -0,0 +1,300 @@
+// Server-side Logic for the Pig validation Capsule.
+//
+// Logic is the single source of truth. Every state change in the game happens
+// through one of these functions and nowhere else: the die is rolled here, the
+// turn rules are enforced here, and the game record lives in the Capsule's own
+// datastore. A human button click and a Mate clay_tool_act call arrive at the
+// same act pipeline with the same rules, so neither party can break a rule the
+// other is bound by, and neither sees state the other cannot.
+//
+// The two seats are "user" and "mate". The server resolves its own actor before
+// calling in, and the human actor maps onto the user seat; seat is never read
+// from caller-supplied text.
+//
+// Rules: seats alternate turns. On your turn you may roll as often as you like;
+// each roll adds to the turn total, but rolling a 1 loses the whole turn total
+// and passes play. Holding banks the turn total into your score, and the first
+// seat to bank at least 100 points wins. A finished game is frozen until
+// someone resets it; only the user may reset a game in progress, because the
+// Capsule belongs to the human, not to the Mate.
+
+var crypto = require("crypto");
+
+var GAME_DOC_ID = "game";
+var TARGET_SCORE = 100;
+var BUST_FACE = 1;
+var USER = "user";
+var MATE = "mate";
+var SEATS = [USER, MATE];
+var SEAT_LABELS = { user: "You", mate: "Your Mate" };
+var MAX_RECENT_ROLLS = 12;
+
+// Every read-modify-write for one stored game runs to completion before the
+// next one starts. Two acts that arrive together would otherwise both validate
+// against the same turn, and the second write would silently discard the first.
+var gameLocks = Object.create(null);
+
+function runExclusive(key, operation) {
+  var previous = gameLocks[key] || Promise.resolve();
+  var settled = previous.then(operation, operation);
+  gameLocks[key] = settled.then(function () {}, function () {});
+  return settled;
+}
+
+function secureRollDie() {
+  return crypto.randomInt(1, 7);
+}
+
+function otherSeat(seat) {
+  return seat === USER ? MATE : USER;
+}
+
+function newGame() {
+  return {
+    status: "playing",
+    turn: USER,
+    scores: { user: 0, mate: 0 },
+    turnTotal: 0,
+    lastRoll: null,
+    lastActor: null,
+    winner: null,
+    target: TARGET_SCORE,
+    sequence: 0,
+    eventSeq: 0,
+    recentRolls: [],
+  };
+}
+
+function safeScore(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 10000 ? value : 0;
+}
+
+// Counters are ordering, not points: they only ever grow, so they carry no
+// upper bound. eventSeq in particular must survive a reset, because a Display
+// that saw event N must treat anything at or below N as already rendered.
+function safeCounter(value) {
+  return Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+// A stored game is data, not a promise about shape. Anything unreadable is
+// replaced by a fresh game rather than trusted.
+function normalizeState(stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) return newGame();
+  if (SEATS.indexOf(stored.turn) === -1) return newGame();
+  if (stored.status !== "playing" && stored.status !== "complete") return newGame();
+  var scores = stored.scores && typeof stored.scores === "object" ? stored.scores : {};
+  var rolls = Array.isArray(stored.recentRolls) ? stored.recentRolls.slice(-MAX_RECENT_ROLLS) : [];
+  return {
+    status: stored.status,
+    turn: stored.turn,
+    scores: { user: safeScore(scores.user), mate: safeScore(scores.mate) },
+    turnTotal: safeScore(stored.turnTotal),
+    lastRoll: Number.isInteger(stored.lastRoll) ? stored.lastRoll : null,
+    lastActor: SEATS.indexOf(stored.lastActor) !== -1 ? stored.lastActor : null,
+    winner: SEATS.indexOf(stored.winner) !== -1 ? stored.winner : null,
+    target: TARGET_SCORE,
+    sequence: safeCounter(stored.sequence),
+    eventSeq: safeCounter(stored.eventSeq),
+    recentRolls: rolls.filter(function (entry) {
+      return entry && typeof entry.text === "string" && Number.isInteger(entry.face);
+    }),
+  };
+}
+
+// recentRolls holds rolls and only rolls, including a bust. Banking and winning
+// are turn outcomes rather than rolls, so they never appear here.
+function appendRoll(state, seat, face, text) {
+  var next = state.sequence + 1;
+  state.sequence = next;
+  state.recentRolls = state.recentRolls
+    .concat([{ id: "roll-" + next, seat: seat, face: face, text: text }])
+    .slice(-MAX_RECENT_ROLLS);
+}
+
+function requirePlayableTurn(state, seat) {
+  if (state.status !== "playing") {
+    throw new Error("This game is already over. Reset it to play again.");
+  }
+  if (state.turn !== seat) {
+    throw new Error("This move is out of turn: " + SEAT_LABELS[state.turn] + " to play.");
+  }
+}
+
+function roll(state, seat, rollDie) {
+  requirePlayableTurn(state, seat);
+  var face = rollDie();
+  if (!Number.isInteger(face) || face < 1 || face > 6) throw new Error("The die produced an invalid face.");
+  state.lastRoll = face;
+  state.lastActor = seat;
+  if (face === BUST_FACE) {
+    appendRoll(state, seat, face, SEAT_LABELS[seat] + " rolled a 1 and lost " + state.turnTotal + " point(s).");
+    state.turnTotal = 0;
+    state.turn = otherSeat(seat);
+    return state;
+  }
+  state.turnTotal += face;
+  appendRoll(state, seat, face, SEAT_LABELS[seat] + " rolled a " + face + " for a turn total of " + state.turnTotal + ".");
+  return state;
+}
+
+function hold(state, seat) {
+  requirePlayableTurn(state, seat);
+  var banked = state.turnTotal;
+  state.scores[seat] += banked;
+  state.lastActor = seat;
+  state.turnTotal = 0;
+  if (state.scores[seat] >= state.target) {
+    state.status = "complete";
+    state.winner = seat;
+    return state;
+  }
+  state.turn = otherSeat(seat);
+  return state;
+}
+
+function reset(state, seat) {
+  if (state.status === "playing" && seat !== USER) {
+    throw new Error("Only the user may reset a game that is still in progress.");
+  }
+  return newGame();
+}
+
+function statusTextFor(state, complete, userTurn) {
+  if (complete) {
+    return state.winner === USER ? "You win this game!" : "Your Mate wins this game.";
+  }
+  if (userTurn) {
+    return state.turnTotal > 0
+      ? "Your turn: roll again or hold to bank " + state.turnTotal + " point(s)."
+      : "Your turn: roll the die.";
+  }
+  return "Your Mate's turn. Moves appear here as they happen.";
+}
+
+// The projection a Display renders and a Mate reads. It adds no meaning that is
+// absent from state: every derived field is a restatement of the fields above.
+// The score series exist because a progress chart binds to a collection.
+function project(state) {
+  var complete = state.status === "complete";
+  var userTurn = !complete && state.turn === USER;
+  return {
+    status: state.status,
+    turn: state.turn,
+    scores: { user: state.scores.user, mate: state.scores.mate },
+    userScoreSeries: [{ seat: SEAT_LABELS.user, value: state.scores.user }],
+    mateScoreSeries: [{ seat: SEAT_LABELS.mate, value: state.scores.mate }],
+    turnTotal: state.turnTotal,
+    turnTotalSeries: [{ label: "Turn total", value: state.turnTotal }],
+    turnTotalText: "Turn total " + state.turnTotal + " of " + state.target + ", " + SEAT_LABELS[state.turn] + " to play.",
+    statusText: statusTextFor(state, complete, userTurn),
+    lastRollText: state.lastRoll === null
+      ? "No rolls yet."
+      : "Last roll: " + state.lastRoll + " by " + SEAT_LABELS[state.lastActor || state.turn] + ".",
+    lastRoll: state.lastRoll,
+    lastActor: state.lastActor,
+    winner: state.winner,
+    target: state.target,
+    recentRolls: state.recentRolls,
+    complete: complete,
+    userTurn: userTurn,
+    eventSeq: state.eventSeq,
+  };
+}
+
+// When the Mate should be engaged is a game rule, so Logic declares it on the
+// event rather than the host inferring it from Pig's fields. The host bridge
+// delivers any declared engagement generically for every Capsule: "turn"
+// means play your seat now, "start" means the human opened a fresh game and
+// you should acknowledge it without acting.
+function engagementFor(seat, actionId, next) {
+  if (seat !== USER) return null;
+  if (next.status === "playing" && next.turn === MATE) return { kind: "turn" };
+  if (actionId === "reset" && next.status === "playing") return { kind: "start" };
+  return null;
+}
+
+// Causality for the live Display: {actor, action, previous, next} plus a
+// monotonic seq. Sending only the new state would make a Mate's move teleport
+// onto the human's screen; the event lets the Display replay and attribute it.
+function buildEvent(seat, actionId, previous, next) {
+  var event = {
+    seq: next.eventSeq,
+    actor: seat,
+    action: actionId,
+    previous: previous,
+    next: next,
+  };
+  var engage = engagementFor(seat, actionId, next);
+  if (engage) event.engage = engage;
+  return event;
+}
+
+function seatFor(context) {
+  var actor = context && context.actor;
+  if (actor === "human" || actor === USER) return USER;
+  if (actor === MATE) return MATE;
+  throw new Error("The Capsule caller seat could not be determined.");
+}
+
+// One act pipeline. The human surface and the Mate MCP surface both land here.
+function createRuntime(options) {
+  options = options || {};
+  var storage = options.storage;
+  var rollDie = typeof options.rollDie === "function" ? options.rollDie : secureRollDie;
+  var lockKey = options.lockKey || "pig";
+  if (!storage) throw new Error("The Pig Capsule requires its datastore.");
+
+  async function writeState(state) {
+    await storage.put({ _id: GAME_DOC_ID, state: state });
+    return state;
+  }
+
+  async function readState() {
+    var doc = await storage.get(GAME_DOC_ID);
+    if (!doc) return writeState(newGame());
+    return normalizeState(doc.state);
+  }
+
+  async function snapshot(context) {
+    seatFor(context);
+    return runExclusive(lockKey, async function () {
+      return project(await readState());
+    });
+  }
+
+  // An act returns {state, event}: the new projection for the caller and the
+  // causal event for every watching Display. Both are built inside the lock,
+  // so seq order on the wire is the order the rules actually ran in.
+  async function act(context, actionId, args) {
+    var seat = seatFor(context);
+    return runExclusive(lockKey, async function () {
+      var state = await readState();
+      var previous = project(state);
+      var next;
+      if (actionId === "roll") next = roll(state, seat, rollDie);
+      else if (actionId === "hold") next = hold(state, seat);
+      else if (actionId === "reset") next = reset(state, seat);
+      else throw new Error("Unknown Pig action '" + String(actionId) + "'.");
+      next.eventSeq = previous.eventSeq + 1;
+      await writeState(next);
+      var projected = project(next);
+      return { state: projected, event: buildEvent(seat, actionId, previous, projected) };
+    });
+  }
+
+  return { snapshot: snapshot, act: act };
+}
+
+module.exports = {
+  GAME_DOC_ID: GAME_DOC_ID,
+  TARGET_SCORE: TARGET_SCORE,
+  SEATS: SEATS,
+  newGame: newGame,
+  normalizeState: normalizeState,
+  project: project,
+  buildEvent: buildEvent,
+  roll: roll,
+  hold: hold,
+  reset: reset,
+  createRuntime: createRuntime,
+};

package/lib/capsule-server-runtimes.js

@@ -0,0 +1,39 @@
+// Trusted server-runtime Logic for shipped Capsules.
+//
+// A server Capsule's Logic runs in this process rather than in a browser
+// worker, so it stays available with no home screen open and owns randomness
+// and hidden state the client must never hold. Only Capsules shipped in
+// lib/capsules/ can claim the server runtime (see tools-registry
+// isTrustedServerRuntime), and only IDs listed here resolve to real Logic.
+//
+// A runtime is created per call. State lives in the Capsule's datastore, never
+// in this module, so nothing here is shared between users.
+
+var path = require("path");
+var toolStorage = require("./tool-storage");
+var toolsRegistry = require("./tools-registry");
+var pigLogic = require("./capsule-pig-logic");
+
+var RUNTIME_FACTORIES = {
+  pig: pigLogic.createRuntime,
+};
+
+function hasRuntime(toolId) {
+  return Object.prototype.hasOwnProperty.call(RUNTIME_FACTORIES, toolId);
+}
+
+function createRuntime(toolId, ctx, options) {
+  if (!hasRuntime(toolId)) return null;
+  var settings = Object.assign({}, options || {});
+  if (!settings.storage) settings.storage = toolStorage.createToolStorage(ctx, toolId);
+  // One stored game, one serialization key, no matter how many runtime
+  // instances are created for it.
+  if (!settings.lockKey) settings.lockKey = path.join(toolsRegistry.resolveToolsRoot(ctx), toolId);
+  return RUNTIME_FACTORIES[toolId](settings);
+}
+
+module.exports = {
+  hasRuntime: hasRuntime,
+  createRuntime: createRuntime,
+  ids: Object.keys(RUNTIME_FACTORIES),
+};

package/lib/capsules/pig/display.js

@@ -0,0 +1,198 @@
+// Pig rich Display element. Runs inside the sandboxed Capsule frame.
+//
+// This element is pure rendering over the same projection the floor renders
+// and a Mate reads: it invents no meaning of its own, and its only outward
+// capability is ClayCapsule.act, which lands in the same Logic pipeline as a
+// floor button. Swapping this file in or out changes nothing a Mate sees.
+
+(function () {
+  "use strict";
+
+  var api = window.ClayCapsule;
+  var state = null;
+  var caption = "";
+  var animating = null;
+
+  document.body.style.margin = "0";
+  document.body.style.background = "#141414";
+  document.body.style.fontFamily = "system-ui, sans-serif";
+
+  var root = document.createElement("div");
+  root.style.padding = "12px";
+  document.body.appendChild(root);
+
+  var captionEl = document.createElement("div");
+  captionEl.style.color = "#b8b8b8";
+  captionEl.style.fontSize = "12px";
+  captionEl.style.minHeight = "16px";
+  captionEl.style.marginBottom = "8px";
+  root.appendChild(captionEl);
+
+  var canvas = document.createElement("canvas");
+  canvas.width = 560;
+  canvas.height = 190;
+  canvas.style.width = "100%";
+  canvas.style.display = "block";
+  root.appendChild(canvas);
+  var ctx = canvas.getContext("2d");
+
+  var controls = document.createElement("div");
+  controls.style.display = "flex";
+  controls.style.gap = "8px";
+  controls.style.marginTop = "10px";
+  root.appendChild(controls);
+
+  var rulesEl = document.createElement("p");
+  rulesEl.textContent = "Pig is a push-your-luck dice game: roll to build this turn's total, but a 1 loses it. Hold to bank your points; the first player to 100 wins.";
+  rulesEl.style.margin = "12px 0 0";
+  rulesEl.style.color = "#b8b8b8";
+  rulesEl.style.fontSize = "12px";
+  rulesEl.style.lineHeight = "1.45";
+  root.appendChild(rulesEl);
+
+  function makeButton(label, action, accent) {
+    var button = document.createElement("button");
+    button.type = "button";
+    button.textContent = label;
+    button.style.flex = "1";
+    button.style.padding = "8px 0";
+    button.style.border = "0";
+    button.style.borderRadius = "8px";
+    button.style.fontSize = "13px";
+    button.style.cursor = "pointer";
+    button.style.background = accent ? "#c96f4a" : "#2c2c2c";
+    button.style.color = accent ? "#141414" : "#d8d8d8";
+    button.addEventListener("click", function () { api.act(action, {}); });
+    controls.appendChild(button);
+    return button;
+  }
+
+  var rollButton = makeButton("Roll", "roll", true);
+  var holdButton = makeButton("Hold", "hold", false);
+  var resetButton = makeButton("Reset", "reset", false);
+
+  function drawBar(y, label, value, target, color) {
+    ctx.fillStyle = "#b8b8b8";
+    ctx.font = "12px system-ui, sans-serif";
+    ctx.fillText(label + "  " + value + " / " + target, 12, y - 6);
+    ctx.fillStyle = "#2c2c2c";
+    ctx.fillRect(12, y, 380, 14);
+    ctx.fillStyle = color;
+    var width = Math.max(0, Math.min(1, value / target)) * 380;
+    ctx.fillRect(12, y, width, 14);
+  }
+
+  function drawDie(face, highlight) {
+    var x = 430;
+    var y = 40;
+    var size = 96;
+    ctx.fillStyle = highlight ? "#f0e5d8" : "#d8d8d8";
+    ctx.beginPath();
+    ctx.roundRect(x, y, size, size, 14);
+    ctx.fill();
+    if (!face) return;
+    ctx.fillStyle = face === 1 ? "#c9564a" : "#141414";
+    var spots = {
+      1: [[0.5, 0.5]],
+      2: [[0.28, 0.28], [0.72, 0.72]],
+      3: [[0.25, 0.25], [0.5, 0.5], [0.75, 0.75]],
+      4: [[0.28, 0.28], [0.72, 0.28], [0.28, 0.72], [0.72, 0.72]],
+      5: [[0.25, 0.25], [0.75, 0.25], [0.5, 0.5], [0.25, 0.75], [0.75, 0.75]],
+      6: [[0.28, 0.22], [0.72, 0.22], [0.28, 0.5], [0.72, 0.5], [0.28, 0.78], [0.72, 0.78]],
+    };
+    var pips = spots[face] || [];
+    for (var i = 0; i < pips.length; i++) {
+      ctx.beginPath();
+      ctx.arc(x + pips[i][0] * size, y + pips[i][1] * size, 7, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+
+  function draw(faceOverride, highlight) {
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    if (!state) {
+      ctx.fillStyle = "#b8b8b8";
+      ctx.font = "13px system-ui, sans-serif";
+      ctx.fillText("Waiting for the game state...", 12, 30);
+      return;
+    }
+    var target = state.target || 100;
+    var scores = state.scores || {};
+    drawBar(36, "You", scores.user || 0, target, "#5a9e6f");
+    drawBar(78, "Your Mate", scores.mate || 0, target, "#6f7fc9");
+    ctx.fillStyle = "#d8d8d8";
+    ctx.font = "13px system-ui, sans-serif";
+    ctx.fillText(state.turnTotalText || "", 12, 122);
+    if (state.complete && state.winner) {
+      ctx.fillStyle = "#f0c96f";
+      ctx.font = "600 15px system-ui, sans-serif";
+      ctx.fillText((state.winner === "user" ? "You win!" : "Your Mate wins!"), 12, 152);
+    }
+    drawDie(faceOverride !== undefined ? faceOverride : state.lastRoll, !!highlight);
+  }
+
+  function syncButtons() {
+    var userTurn = !!(state && state.userTurn);
+    rollButton.disabled = !userTurn;
+    holdButton.disabled = !userTurn;
+    rollButton.style.opacity = userTurn ? "1" : "0.4";
+    holdButton.style.opacity = userTurn ? "1" : "0.4";
+  }
+
+  // Animates a decided roll: a brief pip shuffle that settles on the face the
+  // server already rolled. Pure presentation of a fact already in state.
+  function animateRoll(finalFace, next) {
+    if (animating) clearInterval(animating.timer);
+    var frames = 8;
+    var animation = { timer: null };
+    animating = animation;
+    animation.timer = setInterval(function () {
+      frames--;
+      if (frames <= 0) {
+        clearInterval(animation.timer);
+        if (animating === animation) animating = null;
+        state = next;
+        draw(finalFace, finalFace === 1);
+        syncButtons();
+        return;
+      }
+      draw((frames % 6) + 1, true);
+    }, 55);
+  }
+
+  api.onState = function (nextState) {
+    state = nextState || {};
+    if (!animating) {
+      draw();
+      syncButtons();
+    }
+    captionEl.textContent = caption;
+  };
+
+  api.onEvent = function (event) {
+    if (!event || !event.next) return;
+    var who = event.actor === "mate" ? "Your Mate" : "You";
+    var next = event.next;
+    if (event.action === "roll") {
+      caption = next.lastRoll === 1
+        ? who + " rolled a 1 and lost the turn total."
+        : who + " rolled a " + next.lastRoll + ".";
+      captionEl.textContent = caption;
+      animateRoll(next.lastRoll, next);
+      return;
+    }
+    if (event.action === "hold") {
+      var banked = (event.previous && event.previous.turnTotal) || 0;
+      caption = who + " held and banked " + banked + " point(s).";
+    } else if (event.action === "reset") {
+      caption = who + " started a new game.";
+    }
+    state = next;
+    captionEl.textContent = caption;
+    draw();
+    syncButtons();
+  };
+
+  draw();
+  syncButtons();
+})();

package/lib/capsules/pig/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "pig",
+  "name": "Pig",
+  "runtime": "server",
+  "lucideIcon": "sparkles",
+  "description": "Two-player push-your-luck dice game shared by the user and one Mate.",
+  "useWhen": "Use when the user wants to play Pig, take a turn, or hear how the current game stands.",
+  "skills": "# Pig\n\nA two-seat push-your-luck dice game. The seats are `user` and `mate`; the person holds the user seat and you hold the mate seat. All randomness, turn order, and scoring are enforced server-side by the Capsule's Logic; you cannot roll a die yourself, and neither can the user.\n\n## Rules\n\n- Seats alternate turns. On your turn you may roll as often as you like.\n- Each roll adds its face value to the turn total. Rolling a 1 loses the entire turn total and passes play to the other seat.\n- Holding banks the turn total into your score and passes play.\n- The first seat to bank at least 100 points wins. A finished game is frozen until it is reset.\n- Only the user may reset a game that is still in progress. You may reset once the game is complete.\n\n## How to play\n\n1. `clay_tool_snapshot` with toolId `pig` to read the current state: `turn`, `scores.user`, `scores.mate`, `turnTotal`, `status`, `winner`, and `recentRolls`, which lists recent rolls only and never holds or wins.\n2. Act only when `turn` is `mate`. `clay_tool_act` with actionId `roll`, `hold`, or `reset`. Arguments are not used.\n3. An out-of-turn or post-game call is refused by Logic with an explanatory error. Read the snapshot again rather than retrying blindly.\n4. Every act returns the complete new state, so a snapshot immediately after an act is redundant.\n\n## Playing well\n\nThe interesting part of this Capsule is the judgement call, not the mechanics: decide whether to roll again or hold, and say why in your own words before you act. Typical play holds at a turn total near 20, but the score gap matters more than the rule of thumb, so explain the trade-off you are taking. Never claim a roll result before the act returns it.\n\n## Turn flow\n\nWhen the user's move hands the turn to your seat, Clay wakes you in a dedicated game session with a \"Capsule turn\" message. Take your whole turn there: roll as often as you judge right, then hold (or bust), and stop once the turn passes away from your seat. The user's Display updates live as you act, so never narrate moves you have not made. If nothing wakes you, you are not on turn."
+}

package/lib/capsules/pig/ui.json

@@ -0,0 +1,84 @@
+{
+  "type": "stack",
+  "props": { "gap": "md" },
+  "children": [
+    {
+      "type": "callout",
+      "when": { "equals": { "path": "$state.complete", "value": true } },
+      "props": { "title": "Game over", "text": { "$bind": "$state.statusText", "fallback": "Game over." }, "icon": "circle-check", "variant": "soft" },
+      "else": {
+        "type": "callout",
+        "props": { "title": "Pig", "text": { "$bind": "$state.statusText", "fallback": "Your turn: roll the die." }, "icon": "sparkles", "variant": "soft" }
+      }
+    },
+    {
+      "type": "row",
+      "props": { "gap": "md", "wrap": true },
+      "children": [
+        {
+          "type": "chart",
+          "bind": "userScoreSeries",
+          "props": { "label": "Your score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+        },
+        {
+          "type": "chart",
+          "bind": "mateScoreSeries",
+          "props": { "label": "Your Mate's score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+        }
+      ]
+    },
+    {
+      "type": "row",
+      "props": { "gap": "md", "align": "center", "wrap": true },
+      "children": [
+        {
+          "type": "chart",
+          "bind": "turnTotalSeries",
+          "props": { "label": "Turn total", "kind": "metric", "valueKey": "value" }
+        },
+        { "type": "text", "props": { "text": { "$bind": "$state.lastRollText", "fallback": "No rolls yet." }, "role": "muted" } }
+      ]
+    },
+    {
+      "type": "row",
+      "props": { "gap": "sm", "wrap": true },
+      "children": [
+        {
+          "type": "button",
+          "action": "roll",
+          "when": { "equals": { "path": "$state.userTurn", "value": true } },
+          "props": { "label": "Roll", "variant": "primary" },
+          "else": { "type": "button", "action": "roll", "props": { "label": "Roll", "variant": "primary", "disabled": true } }
+        },
+        {
+          "type": "button",
+          "action": "hold",
+          "when": { "equals": { "path": "$state.userTurn", "value": true } },
+          "props": { "label": "Hold", "variant": "secondary" },
+          "else": { "type": "button", "action": "hold", "props": { "label": "Hold", "variant": "secondary", "disabled": true } }
+        },
+        {
+          "type": "button",
+          "action": "reset",
+          "when": { "equals": { "path": "$state.complete", "value": true } },
+          "props": { "label": "New game", "variant": "primary" },
+          "else": { "type": "button", "action": "reset", "props": { "label": "Start over", "variant": "ghost" } }
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "props": { "label": "Recent rolls", "variant": "inset", "gap": "xs" },
+      "children": [
+        {
+          "type": "list",
+          "bind": "recentRolls",
+          "props": { "variant": "divided", "gap": "xs" },
+          "children": [
+            { "type": "text", "props": { "text": "$item.text", "role": "body" } }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/lib/config.js

@@ -148,12 +148,36 @@ function saveConfig(config) {
   chmodSafe(configPath(), 0o600);
 }
 
+// Does a process with this pid exist? Existence only — never ownership.
+//
+// `process.kill(pid, 0)` sends no signal; it just asks the kernel. Three
+// answers matter, and conflating them has caused real damage:
+//
+//   success -> the process exists and we may signal it
+//   EPERM   -> the process EXISTS but belongs to another user. This is alive.
+//              Reading it as dead is how a daemon started by another OS user
+//              (or under OS-user isolation) got its config cleared and its
+//              socket unlinked by a second daemon, which then started
+//              alongside it.
+//   ESRCH   -> no such process. This is the only "dead".
+//
+// Any other error is a question we could not answer, so we answer "alive":
+// every caller uses this to gate a destructive or duplicating action
+// (clearStaleConfig unlinks the live socket; the migration lock would be
+// stolen), and doing nothing is always the recoverable choice.
+//
+// The pid is validated first, so a malformed value never reaches the kernel
+// call. That matters beyond hygiene: process.kill accepts 0 and negative pids
+// as process-GROUP selectors and returns success for them, so an unvalidated
+// 0 or -1 in a config file used to report a live daemon that does not exist.
 function isPidAlive(pid) {
+  if (typeof pid !== "number" || !isFinite(pid) || Math.floor(pid) !== pid || pid <= 0) return false;
   try {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    return false;
+    if (e && e.code === "ESRCH") return false;
+    return true;
   }
 }