Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 0 additions & 98 deletions .agents/skills/beads/SKILL.md

This file was deleted.

4 changes: 0 additions & 4 deletions .agents/skills/beads/agents/openai.yaml

This file was deleted.

2 changes: 1 addition & 1 deletion .agents/skills/pinpoint-chores/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Then work the checklist. For each item, note findings as a comment on the bead (

- If it's newer than the current pin (mind major bumps — read the pnpm release notes/migration guide first), update `packageManager` in `package.json` with the new version and its sha512 integrity hash (e.g. from `npm view pnpm@<version> dist.integrity` converted to `+sha512.<hex>`), run `mise lock` and then `mise install --locked`, then verify no unexpected `pnpm-lock.yaml` churn (`pnpm install --frozen-lockfile`), `pnpm audit --audit-level=high` still resolves, and `pnpm run check` is green. PR it through the normal workflow; file a bead if a major bump needs real migration work.
- **Vercel CLI pin** (PP-h2ui.7). Privileged Vercel CLI invocations use one repository-owned wrapper: `scripts/workflow/preview/vercel-cli.sh`. Compare the pinned `VERCEL_CLI_VERSION` against the latest release on npm (applying a 14/30-day cooldown). Bumping is a single-site edit in `scripts/workflow/preview/vercel-cli.sh`.
- **bd and Dolt compatibility version pins** (from the 2026-08-16 shared-DB schema incident). PinPoint declares exact compatibility versions for `bd` and `dolt` at a **single source**: `scripts/beads-compatibility.json`. The cloud setup script (`scripts/beads-cloud-setup.sh`), runtime guards (`scripts/beads-cloud-init.sh`), and Bazzite services consume or validate this manifest. When Tim's local/Bazzite tools move past the pins, bump **`scripts/beads-compatibility.json`** — cloud routines and services refuse to run until installed binaries match. Exact-pin is deliberate: an accidental _newer_ release migrated the shared DB and locked every client out for two days, so a loud refusal is the safe failure. Compare the pins against installed `bd version` and `dolt version`; bump only once newer versions are tested and running clean locally.
- **bd and Dolt compatibility version pins** (from the 2026-08-16 shared-DB schema incident). PinPoint declares exact versions for `bd` and `dolt` at a **single source**: `scripts/beads-compatibility.json`. Cloud routines install exactly those pins (`scripts/beads-cloud-setup.sh`) and refuse to touch the DB on a mismatch (`scripts/beads-cloud-init.sh`); the Mac's user-global mise declarations in dotfiles are checked against the same file by a dotfiles test. For an upgrade, validate the newer tools against the local embedded database and a `bd dolt push` round-trip, bump the manifest and its archive digests, then update the dotfiles mise pins to match. Exact pins are deliberate: an accidental _newer_ release migrated the shared DB and locked every client out for two days, so a loud refusal is the safe failure.

2. **TypeScript compiler maintenance**
- TypeScript 7 is installed as `typescript`; its native `tsc` runs the app, test, E2E, and Next build type checks. Read `docs/plans/2026-06-27-typescript-7-upgrade-plan.md` only for the rollout record.
Expand Down
6 changes: 5 additions & 1 deletion .claude/hooks/inject-beads-actor.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,14 @@ function resolveActor(sessionId, cwd) {
if (!home) {
return fallback;
}
// The huddle is a plugin checked out at ~/Code/huddle; the launchd job in
// dotfiles uses the same path. Not the harness plugin cache, whose path
// carries the plugin version and changes on every release.
const whoami = path.join(
home,
".agents",
"Code",
"huddle",
"lib",
"huddle-whoami.sh"
);
const name = execFileSync("bash", [whoami, "whoami", sessionId], {
Expand Down
18 changes: 10 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,16 @@ Before exploring or changing non-mechanical product behavior, read
ADRs. Skip it for mechanical changes that do not affect product behavior or
domain language.

**The huddle is global, not a PinPoint subsystem.** Its implementation, trusted
repository registry, harness registrations, tests, and user services live in
Tim's dotfiles. Shared scripts are at `~/.agents/huddle/`; agent-writable state
lives under `$XDG_STATE_HOME/agents-huddle/agent/`. Global hooks silently
self-disable outside registered repositories. The Mac updater and Bazzite
leader service own fetch/fast-forward work; Bazzite alone posts merge
announcements. PinPoint keeps only its Beads actor hook, which asks the global
`huddle-whoami.sh` interface for the registered identity.
**The huddle is global, not a PinPoint subsystem.** Its implementation, skill,
and tests live in the public `timothyfroehlich/huddle` repository, installed as
a plugin in each harness and checked out at `~/Code/huddle`; the trusted
repository registry and the Mac launchd job stay in Tim's dotfiles. Shared
scripts are at `~/Code/huddle/lib/`; agent-writable state lives under
Comment thread
timothyfroehlich marked this conversation as resolved.
`$XDG_STATE_HOME/agents-huddle/agent/`. Plugin hooks silently self-disable
outside registered repositories. The Mac leader service owns fetch and
fast-forward work and posts merge announcements. PinPoint keeps only its Beads
actor hook, which asks the global `huddle-whoami.sh` interface for the
registered identity.

## 4. Environment

Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,13 +88,13 @@ Homebrew, or another version manager.

### Tool Ownership

| Surface | Authority |
| :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| Project Node, Python, Ruff, and Supabase CLI | Exact pins in `mise.toml`; resolved artifacts in `mise.lock` |
| pnpm executable | Exact version and sha512 integrity in `package.json#packageManager`, installed by mise |
| Project commands | `package.json#scripts`; mise resolves tools but does not duplicate the task namespace |
| Local/Bazzite `bd` and Dolt | User-global mise declarations checked against `scripts/beads-compatibility.json` |
| Cloud-routine `bd` and Dolt | `scripts/beads-cloud-setup.sh` plus `scripts/beads-cloud-init.sh`; this path remains separate because cloud routines cannot reach the tailnet |
| Surface | Authority |
| :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| Project Node, Python, Ruff, and Supabase CLI | Exact pins in `mise.toml`; resolved artifacts in `mise.lock` |
| pnpm executable | Exact version and sha512 integrity in `package.json#packageManager`, installed by mise |
| Project commands | `package.json#scripts`; mise resolves tools but does not duplicate the task namespace |
| Local `bd` and Dolt | User-global mise declarations in dotfiles, checked against `scripts/beads-compatibility.json` by a dotfiles test |
| Cloud-routine `bd` and Dolt | `scripts/beads-cloud-setup.sh` plus `scripts/beads-cloud-init.sh`, installing exactly the pins in `scripts/beads-compatibility.json` |

Vercel does not install or invoke mise. `package.json#engines` is its Node
compatibility contract, `vercel-build` retains the production migration/build
Expand Down
35 changes: 25 additions & 10 deletions docs/runbooks/cloud-routines-beads-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,24 @@ the cloud checkout has no beads data).
This runbook documents the cloud **environment** configuration that grants a
routine full read + write to that DB. Proven end-to-end on 2026-07-11 (PP-3x7s).

**Model:** hybrid — routines run unattended and may write beads; a local
"chores" session reviews and acts on them. Dolt merges independent rows and
tables, but it does not semantically merge two edits to the same issue row.
Concurrent cloud and live-server updates to one issue can therefore stop the
bridge with a conflict even when both edits are legitimate. The bridge fails
closed so an operator can preserve the intended fields from both sides; never
resolve these conflicts with a blanket newest-row, `--ours`, or `--theirs`
policy. The beads remote-migrate gate remains the schema-version backstop.
**Model:** hub and spokes, with DoltHub as the hub. Tim's Mac holds a local
embedded Dolt database; it pushes to DoltHub automatically (`dolt.auto-push`,
debounced) and the huddle hooks push and pull on every throttled session poll,
so the Mac converges within minutes of any write. A cloud routine is the other
spoke: `beads-cloud-init.sh` clones from DoltHub (or pulls, if the sandbox
survived), the routine writes, and it pushes with `bd dolt push` before the
sandbox ends. There is no server and no bridge; a local "chores" session
reviews what routines wrote.

Dolt merges independent rows and cells on pull, so two sides editing different
issues, or different fields of one issue, never conflict. Two edits to the same
cell do. Where that surfaces depends on who moves second: a cloud push that is
not a fast-forward is rejected, so the routine must `bd dolt pull` and push
again in the same run or its writes end with the sandbox; a conflicting pull on
the Mac fails, and the huddle rotation refuses to proceed until `bd dolt pull`
succeeds. Resolve it there, on the Mac, preserving the intended fields from both
sides; never with `--force` on a push or a blanket newest-row policy. The beads
remote-migrate gate remains the schema-version backstop.

## The three things that make it work

Expand Down Expand Up @@ -101,8 +111,9 @@ That script installs `dolt` (pinned) and `bd` (pinned); the agent then runs
lockout was a `bd` schema migration — `bd` owns `schema_migrations` and the
additive migrations that broke it, while `dolt` is the storage engine. Pinning
both `bd` and `dolt` to exact versions in `scripts/beads-compatibility.json`
guarantees consistent schema handling, client-server wire compatibility, and
reproducibility across cloud sandboxes, Mac laptops, and Bazzite hosts.
guarantees consistent schema handling and reproducibility across cloud
sandboxes and the Mac. The Mac runs the same pins through user-global mise
Comment thread
timothyfroehlich marked this conversation as resolved.
declarations in Tim's dotfiles, checked against this file by a dotfiles test.

**The toolchain pins are single-source.** `beads-cloud-setup.sh` reads both
`bd` and `dolt` versions from `scripts/beads-compatibility.json` and installs
Expand All @@ -124,6 +135,10 @@ version guard in `scripts/beads-cloud-init.sh`, which refuses to touch the DB
unless both the installed `bd` and `dolt` equal their pins in
`scripts/beads-compatibility.json`.

An upgrade is a paired rollout: validate the newer tools against the local
embedded database, bump this manifest and its archive digests, then update
the dotfiles mise pins to match.

## Credential setup (one-time)

Use a **dedicated** DoltHub credential for the cloud, not a personal machine key,
Expand Down
Loading
Loading