[allisonmahmood]

Stacked on #909's branch for its welcome-page predicate; merges with the onboarding stack.

What changed

Activation is now decided: a patch someone else at the company opens within 7 days of the person joining, with the welcome page excluded. Patchy already recorded each member's opens for their own Home, but nothing reported "a colleague opened your patch for the first time", so the metric couldn't be read in PostHog. Now a member's first open of a colleague's company patch reports patch.first_opened, and docs/product.md › Analytics records the activation query and its public-patch gap.

Closes #912. Part of #906.

• Patches.recordOpen now returns whether its upsert inserted (RETURNING xmax = 0, which works on any Postgres version). A member's first record of a patch is reported once, even when opens race. A stale version or an off patch records nothing and returns false.
• Serving (Pages.ts) reports patch.first_opened when that open was a first and the opener isn't the owner. The event carries patchId, tier, ownerUserId and welcomePage (feat(ui): Final step, a panel over Home until your agent is connected #909's isWelcomePage), and its principal is the opener. It carries no page content. The open and its report are one uninterruptible step. sql-pg gives an interrupted statement 10 ms before cancelling it, so a reader who leaves mid-open could otherwise commit a first open that never reports; the next open isn't first, so that event would be lost for good. track only queues, so the page doesn't wait on PostHog, and an event failure never fails the page.
• The catalogue (Analytics.ts) records this as the one exception to "serving isn't a business event", and says why. The Analytics and Patches glossaries, GLOSSARY-MAP.md and OPERATIONS' business-event list follow.
• The known gap: public patches record no member's opens, even for a signed-in colleague, so they never count towards activation. Opens recorded before this release report nothing either. Both are written into product.md.

Look at

1. First-open detection under a race. The test holds an uncommitted insert of the same patch_opens row and waits until three recordOpen calls are blocked on it in pg_stat_activity. Then it rolls the insert back. Exactly one call must report the insert. Before (old recordOpen, same tests):

 FAIL  packages/patches/src/Patches.test.ts > Patches > remembers each member's opens of live patches, halving every week
AssertionError: expected undefined to be true
 FAIL  packages/patches/src/Patches.test.ts > Patches > lets exactly one of a member's racing opens be their first
AssertionError: expected +0 to deeply equal 1
 FAIL  packages/serving/src/Pages.test.ts > pages > reports a colleague's first open of a patch, and no other open
AssertionError: expected [] to deeply equal [ Array(1) ]
      Tests  3 failed | 5 passed | 68 skipped (76)

After:

 ✓ Patches > remembers each member's opens of live patches, halving every week 35ms
 ✓ Patches > lets exactly one of a member's racing opens be their first 14ms
 ✓ pages > records a member's open of the address, never the content URL or a public page 39ms
 ✓ pages > reports a colleague's first open of a patch, and no other open 37ms
 ✓ pages > serves the page when recording an open fails 16ms

The race test passed in each of 5 consecutive runs.

2. What emits and what doesn't (Pages.test.ts). These run against a real socket:

• the owner's own first open: no event;
• a colleague on a public patch: no event;
• a colleague on ~v/1 after v2 is out: no event;
• the colleague's first open of the current version: exactly one event, { patchId, ownerUserId, tier: 0, welcomePage: false };
• opening it again: nothing more;
• a colleague opening a welcome page: welcomePage: true.

3. A reader who leaves mid-open still counts. The test makes recording the open take a second and interrupts the request during it. It then requires both the patch_opens row and the event. Without Effect.uninterruptible the run fails with AssertionError: expected +0 to equal 1, because the cancelled open records nothing. With it, the run passes.

How it was verified

• pnpm exec vitest run packages/patches/src/Patches.test.ts packages/serving/src/Pages.test.ts packages/analytics: 96 passed.
• packages/portal/src/PortalPages.test.ts: 84 passed. It calls recordOpen and ignores the new result.
• pnpm typecheck (src and tests) and pnpm lint: clean. Prettier ran on every changed file.
• I didn't run pnpm verify, e2e or the browser suites, because this machine is shared.
• The activation query is written as a definition over user.joined and patch.first_opened, keyed by ownerUserId. I haven't run it in PostHog: the event only exists once this ships.

Release impact

• Breaking — requires action from anyone already running this
• Not breaking — no action required

This adds one event and changes an internal return type. There's no schema change, migration, CLI or API change.

• What does a revert leave behind? Only patch.first_opened events already sent to PostHog. patch_opens rows are written exactly as before.
• Does the release before it still work with that? Yes.

Made by Claude Opus 5.5 in Claude Code, running in T3 Code.

🤖 Generated with Claude Code

[allisonmahmood]

GPT 6.1 Sol (xhigh) reviewed this. Two should-fixes, both fixed in f860a0e, and the branch is rebased onto #916's latest commit:

1. Effect.uninterruptible around the whole open meant a disconnected reader's statement could wait on locks indefinitely. Enough of those could exhaust the pool and hold up shutdown. The open now runs through withReportedCommit: the insert and its lock waits stay cancellable, and only the commit and its report are protected. The disconnect test now asserts that an abandoned open leaves nothing recorded and unreported.
2. The privacy sentence in docs/product.md now says what reaches PostHog: patch.first_opened is the one business event for opens, and the request diagnostics (wide.request) already carry viewer and patch ids for every company-page open.