Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Merge batch 11-05 i1225b: #3088 #3084 (#3092)

0xken1512c7aa22f604
diff --git a/backend/integration/productUsageConflicts.test.ts b/backend/integration/productUsageConflicts.test.ts
index 1b99eb075..901480227 100644
--- a/backend/integration/productUsageConflicts.test.ts
+++ b/backend/integration/productUsageConflicts.test.ts
@@ -42,11 +42,14 @@ it('a fleet reporting at once is counted whole, with no report refused', async (
const answers = await Promise.allSettled(reports.map((report, i) => usage.ingestProductUsage(`6a00000000000000000${String(i).padStart(5, '0')}`, report, now)))
expect(answers.filter(a => a.status === 'rejected').map(a => (a as PromiseRejectedResult).reason?.code)).toEqual([])
expect(answers.map(a => (a as PromiseFulfilledResult<unknown>).value)).toEqual(reports.map(() => ({ accepted: true })))
+ expect(await total('health_cli_collector_days')).toBeUndefined()
+ await usage.flushRelayUsage()
expect(await total('health_cli_collector_days')).toBe(64)
expect(await total('turns_started')).toBe(128)
expect(await total('turns_ended')).toBe(32)
expect(await total('breakdown:release:cli:0.4.92:turns_started')).toBe(128)
- expect(await db.productUsageReceipt.count()).toBe(64)
+ // The 64 reports' receipts and the one receipt of the flush that wrote their totals.
+ expect(await db.productUsageReceipt.count()).toBe(65)
}, 60000)
it('a report sent again after its answer was lost counts once', async () => {
@@ -54,6 +57,7 @@ it('a report sent again after its answer was lost counts once', async () => {
const answers = await Promise.all([1, 2, 3].map(() => usage.ingestProductUsage('6a0000000000000000000b01', report, now)))
expect(answers).toEqual([{ accepted: true }, { accepted: true }, { accepted: true }])
expect(await usage.ingestProductUsage('6a0000000000000000000b01', report, now)).toEqual({ accepted: true })
+ await usage.flushRelayUsage()
expect(await total('launch_unobserved')).toBe(3)
}, 60000)
@@ -66,6 +70,8 @@ it('four backend processes reporting at once still count every report', async ()
{ schemaVersion: 1, revision: 0, id: randomUUID(), day: '2026-10-28', context, counters: { queue_capped: 1 } }, now)))
const answers = await Promise.allSettled(sent)
expect(answers.filter(a => a.status === 'rejected').map(a => (a as PromiseRejectedResult).reason?.code)).toEqual([])
+ // Every process's sums, written at once to the same rows.
+ await Promise.all(processes.map(each => each.flushRelayUsage()))
expect(await total('queue_capped')).toBe(192)
}, 60000)
diff --git a/backend/integration/productUsageReceipts.test.ts b/backend/integration/productUsageReceipts.test.ts
index 402ceb274..cc5edfce7 100644
--- a/backend/integration/productUsageReceipts.test.ts
+++ b/backend/integration/productUsageReceipts.test.ts
@@ -52,6 +52,8 @@ const KEPT = [...days('2026-09-28', '2026-10-02'), '2026-10-30'].flatMap(day =>
const TOTALS = [{ dayUtc: new Date('2026-10-20'), metric: 'turns_started', value: 41 }, { dayUtc: new Date('2026-11-01'), metric: 'turns_started', value: 7 }]
beforeEach(async () => {
+ // Totals a test left waiting in memory must not land in the next test's database.
+ await usage.flushRelayUsage().catch(() => {})
// The database as it is before the release: no receipt rule yet.
await db.$runCommandRaw({ collMod: 'product_usage_receipts', validator: {}, validationLevel: 'off' })
await db.productUsageReceipt.deleteMany()
@@ -133,8 +135,13 @@ const turnsEnded = async (day: string) =>
(await db.productUsageTotal.findUnique({ where: { dayUtc_metric: { dayUtc: new Date(day), metric: 'turns_ended' } } }))?.value
const drain = async (at = now) => { while ((await pass(at)).removed) { /* the next chunks */ } }
const account = '6a0000000000000000000c01'
-const signedIn = (report: ReturnType<typeof late>, at = now) => usage.ingestProductUsage(account, { schemaVersion: 1, revision: 0,
- ...report, context: { surface: 'cli', release: '0.4.92', platform: 'macos', channel: 'production' } }, at)
+// A report's totals wait in memory until the minute's flush; the flush is part of counting it.
+const signedIn = async (report: ReturnType<typeof late>, at = now) => {
+ const answer = await usage.ingestProductUsage(account, { schemaVersion: 1, revision: 0,
+ ...report, context: { surface: 'cli', release: '0.4.92', platform: 'macos', channel: 'production' } }, at)
+ await usage.flushRelayUsage()
+ return answer
+}
it('an old server still running cannot count a late report twice across the sweep (review of c20be500d)', async () => {
// 2 November 00:01: no report for today yet, and an old server takes a 29 October report.
@@ -294,7 +301,10 @@ it('counting stays exact: a report inside the window counts once across the swee
expect(await usage.ingestProductUsage('6a0000000000000000000c01', report, now)).toEqual({ accepted: true })
expect(await db.productUsageReceipt.findUnique({ where: { id: report.id } })).toEqual({ id: report.id, expiresAt: new Date('2026-11-05'), life: 4 })
while ((await pass()).removed) { /* every old receipt outside the new life */ }
+ // The rule is up now: the flush writing the report's totals must carry its life too, or it would count nothing.
+ await usage.flushRelayUsage()
expect(await usage.ingestProductUsage('6a0000000000000000000c01', report, now)).toEqual({ accepted: true })
+ await usage.flushRelayUsage()
expect(await turnsEnded()).toBe(2)
const late = { ...report, id: randomUUID(), day: '2026-10-30' }
diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.ts
index 16e4dbc6c..daa594544 100644
--- a/backend/src/lib/productUsage.test.ts
+++ b/backend/src/lib/productUsage.test.ts
@@ -19,13 +19,14 @@ const db = vi.hoisted(() => ({
vi.mock('./prisma.js', () => ({ prisma: db }))
// A configured key, so deletion through setProductUsageChoice and the legacy delete path is real.
vi.mock('../config/env.js', () => ({ env: { PRODUCT_USAGE_SUBJECT_KEY: 'k'.repeat(32) } }))
-import { activitySubject, deleteActivity, deleteLegacyProductUsage, ensureProductUsageExpiry, markActivity, resetActivityMarksForTests, resetStaffAccountsForTests, ingestProductUsage, ingestSetupUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice, flushRelayUsage, resetRelayUsageForTests } from './productUsage.js'
+import { activitySubject, deleteActivity, deleteLegacyProductUsage, ensureProductUsageExpiry, markActivity, resetActivityMarksForTests, resetStaffAccountsForTests, ingestProductUsage, ingestSetupUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice, flushRelayUsage, resetRelayUsageForTests, startRelayUsageFlush } from './productUsage.js'
import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_USAGE_METRICS, type ProductUsageReport } from '../types/productUsage.js'
it('commits release and platform margins under the same unlinked receipt and discards development reports', async () => {
const context = { surface: 'desktop', release: '1.2.73', platform: 'macos', channel: 'production' } as const
expect(await ingestProductUsage('PRIVATE_ACCOUNT', { ...report, context }, now)).toEqual({ accepted: true })
expect(db.$transaction).toHaveBeenCalledOnce()
+ await flushRelayUsage()
expect(db.$runCommandRaw.mock.calls[0][0].updates).toHaveLength(6)
const stored = JSON.stringify([db.productUsageReceipt.createMany.mock.calls, db.$runCommandRaw.mock.calls])
expect(stored).not.toContain('PRIVATE_ACCOUNT')
@@ -69,6 +70,7 @@ describe('kept apart', () => {
accounts('[email protected]')
const context = { surface: 'phone', release: '1.0.7', platform: 'ios', channel: 'production' } as const
expect(await ingestProductUsage('team-account', { ...report, day: '2026-10-12', context }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(stored()).toEqual(expect.arrayContaining(['staff:turns_started', 'staff:breakdown:release:phone:1.0.7:turns_started',
'staff:health_phone_report_late']))
expect(stored().every(metric => metric.startsWith('staff:'))).toBe(true)
@@ -77,6 +79,7 @@ describe('kept apart', () => {
it('keeps a tester\'s build under testing:, without margins, whoever signed in', async () => {
const context = { surface: 'phone', release: '1.0.7', platform: 'ios', channel: 'testing' } as const
expect(await ingestProductUsage('someone', { ...report, context }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(stored()).toEqual(['testing:turns_started', 'testing:turns_ended'])
// A build's channel decides it: no account is read for it.
expect(db.user.findMany).not.toHaveBeenCalled()
@@ -86,6 +89,7 @@ describe('kept apart', () => {
const context = { surface: 'phone', release: '1.0.7', platform: 'ios', channel: 'production' } as const
await ingestProductUsage('person', { ...report, context }, now)
await ingestProductUsage('person', { ...report, id: 'cf1c5a03-388c-4265-b5fb-a4c3d47e4080', context }, now)
+ await flushRelayUsage()
expect(stored().filter(metric => metric.includes(':') && !metric.startsWith('breakdown:'))).toEqual([])
expect(stored()).toContain('turns_started')
expect(db.user.findMany).toHaveBeenCalledOnce()
@@ -94,6 +98,7 @@ describe('kept apart', () => {
it('reads no account for signed-out setup counts', async () => {
expect(await ingestSetupUsage({ id: 'cf1c5a03-388c-4265-b5fb-a4c3d47e4081', day: '2026-10-13',
counters: { setup_phone_first_open: 1 } }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(stored()).toEqual(['setup_phone_first_open'])
expect(db.user.findMany).not.toHaveBeenCalled()
})
@@ -123,6 +128,7 @@ it('names every launch code in each of its families, once, as a fixed word that
it('stores launch codes as day totals like any other counter', async () => {
const counters = { launch_failed_other: 2, launch_failed_code_invalid_prompt: 1, launch_failed_code_unlisted: 1, first_launch_claude_signed_in: 1 }
expect(await ingestProductUsage('private-account', { ...report, counters }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(db.$runCommandRaw.mock.calls[0][0].updates.map((u: { q: { metric: string }; u: unknown }) => [u.q.metric, u.u]))
.toEqual(Object.entries(counters).map(([metric, value]) => [metric, { $inc: { value } }]))
})
@@ -132,6 +138,7 @@ it('accepts the Windows and Git helper refusals that older launch reports called
'invalid_branch', 'branch_switch_failed', 'branch_in_use', 'worktree_failed']
const counters = Object.fromEntries(codes.map(code => [`launch_failed_code_${code}`, 1]))
expect(await ingestProductUsage('private-account', { ...report, counters }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(db.$runCommandRaw.mock.calls[0][0].updates.map((u: { q: { metric: string } }) => u.q.metric))
.toEqual(Object.keys(counters))
})
@@ -144,6 +151,7 @@ it('stores setup reasons in separate families without reinterpreting the other-f
launch_failed_other: 1, launch_failed_code_worktree_failed: 1,
}
expect(await ingestProductUsage('private-account', { ...report, counters }, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
const stored = db.$runCommandRaw.mock.calls[0][0].updates.map((u: { q: { metric: string }; u: unknown }) => [u.q.metric, u.u])
expect(stored).toEqual(Object.entries(counters).map(([metric, value]) => [metric, { $inc: { value } }]))
expect(JSON.stringify(stored)).not.toContain('private-account')
@@ -196,12 +204,17 @@ describe('aggregate ingestion', () => {
expect(db.$transaction).toHaveBeenCalledTimes(2)
expect(db.productUsagePreference.findMany.mock.calls[1][0].where.userId.in).toEqual(['account-1', 'account-2', 'account-3'])
expect(receipts()).toEqual(['receipt-0', 'receipt-1', 'receipt-2', 'receipt-3'])
- expect(db.$runCommandRaw.mock.calls[1][0].updates.map((u: { q: { metric: string }; u: unknown }) => [u.q.metric, u.u]))
- .toEqual([['turns_started', { $inc: { value: 12 } }], ['turns_ended', { $inc: { value: 9 } }]])
+ await flushRelayUsage()
+ expect(db.$runCommandRaw.mock.calls[0][0].updates.map((u: { q: { metric: string }; u: unknown }) => [u.q.metric, u.u]))
+ .toEqual([['turns_started', { $inc: { value: 16 } }], ['turns_ended', { $inc: { value: 12 } }]])
})
it('stores only totals and an unlinked receipt, in one transaction', async () => {
expect(await ingestProductUsage('private-account', report, now)).toEqual({ accepted: true })
expect(db.$transaction).toHaveBeenCalledOnce()
+ expect(db.productUsageReceipt.createMany).toHaveBeenCalledExactlyOnceWith({ data: [
+ { id: report.id, expiresAt: new Date('2026-10-17T00:00:00.000Z'), life: 4 }] })
+ expect(db.$runCommandRaw).not.toHaveBeenCalled()
+ await flushRelayUsage()
expect(db.$runCommandRaw).toHaveBeenCalledOnce()
expect(db.$runCommandRaw.mock.calls[0][0]).toEqual({
update: 'product_usage_totals', ordered: true, updates: [
@@ -209,8 +222,6 @@ describe('aggregate ingestion', () => {
{ q: { dayUtc: { $date: '2026-10-13T00:00:00.000Z' }, metric: 'turns_ended' }, u: { $inc: { value: 3 } }, upsert: true },
],
})
- expect(db.productUsageReceipt.createMany).toHaveBeenCalledExactlyOnceWith({ data: [
- { id: report.id, expiresAt: new Date('2026-10-17T00:00:00.000Z'), life: 4 }] })
const stored = JSON.stringify([db.$runCommandRaw.mock.calls, db.productUsageReceipt.createMany.mock.calls])
for (const forbidden of ['private-account', 'userId', 'machineId', 'agentId', 'revision', 'counters', 'receivedAt']) expect(stored).not.toContain(forbidden)
})
@@ -249,16 +260,17 @@ describe('aggregate ingestion', () => {
gate.resolve()
expect(await Promise.all([first, ...twice])).toEqual(Array(3).fill({ accepted: true }))
expect(receipts()).toEqual(['receipt-0', report.id])
- expect(db.$runCommandRaw.mock.calls[1][0].updates[0].u).toEqual({ $inc: { value: 4 } })
+ await flushRelayUsage()
+ expect(db.$runCommandRaw.mock.calls[0][0].updates[0].u).toEqual({ $inc: { value: 8 } })
})
- it('does not mistake a rolled-back aggregate creation race for a received report', async () => {
- db.$runCommandRaw.mockRejectedValue({ code: 'P2002' })
+ it('does not mistake a rolled-back receipt creation race for a received report', async () => {
+ db.productUsageReceipt.createMany.mockRejectedValue({ code: 'P2002' })
await expect(ingestProductUsage('a', report, now)).rejects.toMatchObject({ code: 'P2002' })
expect(db.$transaction).toHaveBeenCalledTimes(4)
expect(delay).toHaveBeenCalledTimes(3)
})
it.each(['P2034', 'P2002'])('retries a fast %s conflict with the same receipt and a fresh permission check', async code => {
- db.$runCommandRaw.mockRejectedValueOnce({ code })
+ db.productUsageReceipt.createMany.mockRejectedValueOnce({ code })
expect(await ingestProductUsage('private-account', report, now)).toEqual({ accepted: true })
expect(db.$transaction).toHaveBeenCalledTimes(2)
expect(db.productUsagePreference.findMany).toHaveBeenCalledTimes(2)
@@ -268,14 +280,14 @@ describe('aggregate ingestion', () => {
expect(vi.mocked(delay).mock.calls[0][0]).toBeLessThan(75)
})
it('retries a Mongo lock wait like a conflict, with the same receipt', async () => {
- db.$runCommandRaw.mockRejectedValueOnce(new Error('Error code 24 (LockTimeout): Unable to acquire IX lock, labels: {"TransientTransactionError"}'))
+ db.productUsageReceipt.createMany.mockRejectedValueOnce(new Error('Error code 24 (LockTimeout): Unable to acquire IX lock, labels: {"TransientTransactionError"}'))
expect(await ingestProductUsage('a', report, now)).toEqual({ accepted: true })
expect(db.$transaction).toHaveBeenCalledTimes(2)
expect(db.productUsageReceipt.createMany.mock.calls[0]).toEqual(db.productUsageReceipt.createMany.mock.calls[1])
expect(delay).toHaveBeenCalledOnce()
})
it('rechecks a sharing-off choice before retrying the transaction', async () => {
- db.$runCommandRaw.mockRejectedValueOnce({ code: 'P2034' })
+ db.productUsageReceipt.createMany.mockRejectedValueOnce({ code: 'P2034' })
choices({ userId: 'a', enabled: true, revision: 0 })
choices({ userId: 'a', enabled: false, revision: 1 })
expect(await ingestProductUsage('a', report, now)).toMatchObject({ accepted: false, reason: 'CHOICE_CHANGED' })
@@ -314,6 +326,75 @@ describe('aggregate ingestion', () => {
})
})
+describe('report totals wait in memory', () => {
+ const updates = (): Array<[string, string, number]> => db.$runCommandRaw.mock.calls.flatMap(([command]) =>
+ (command as { updates: Array<{ q: { dayUtc: { $date: string }; metric: string }; u: { $inc: { value: number } } }> }).updates
+ .map(u => [u.q.dayUtc.$date.slice(0, 10), u.q.metric, u.u.$inc.value] as [string, string, number])).sort()
+
+ it('N reports cost no totals write, then one write per counter a minute later, with no read before it', async () => {
+ for (let i = 0; i < 40; i++) expect(await ingestProductUsage('a', { ...report, id: `receipt-${i}` }, now)).toEqual({ accepted: true })
+ expect(db.$runCommandRaw).not.toHaveBeenCalled()
+ await flushRelayUsage()
+ expect(db.$runCommandRaw).toHaveBeenCalledOnce()
+ expect(updates()).toEqual([['2026-10-13', 'turns_ended', 120], ['2026-10-13', 'turns_started', 160]])
+ for (const reads of ['findMany', 'groupBy', 'update', 'upsert'] as const) expect(db.productUsageTotal[reads]).not.toHaveBeenCalled()
+ await flushRelayUsage()
+ expect(db.$runCommandRaw).toHaveBeenCalledOnce()
+ })
+
+ it('on the minute timer, a busy minute is one write per counter, and a clean stop flushes what is left', async () => {
+ vi.useFakeTimers()
+ try {
+ const stop = startRelayUsageFlush()
+ for (let i = 0; i < 25; i++) await ingestProductUsage('a', { ...report, id: `a-${i}` }, now)
+ expect(db.$runCommandRaw).not.toHaveBeenCalled()
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(db.$runCommandRaw).toHaveBeenCalledOnce()
+ expect(updates()).toEqual([['2026-10-13', 'turns_ended', 75], ['2026-10-13', 'turns_started', 100]])
+ db.$runCommandRaw.mockClear()
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(db.$runCommandRaw).not.toHaveBeenCalled()
+ await ingestProductUsage('a', { ...report, id: 'late' }, now)
+ await stop()
+ expect(updates()).toEqual([['2026-10-13', 'turns_ended', 3], ['2026-10-13', 'turns_started', 4]])
+ } finally { vi.useRealTimers() }
+ })
+
+ it('a day boundary still splits the counts: each report lands on its own day', async () => {
+ await ingestProductUsage('a', { ...report, id: 'r1', day: '2026-10-12' }, now)
+ await ingestProductUsage('a', { ...report, id: 'r2', day: '2026-10-13' }, now)
+ await ingestProductUsage('a', { ...report, id: 'r3', day: '2026-10-13' }, now)
+ await flushRelayUsage()
+ expect(updates()).toEqual([['2026-10-12', 'turns_ended', 3], ['2026-10-12', 'turns_started', 4],
+ ['2026-10-13', 'turns_ended', 6], ['2026-10-13', 'turns_started', 8]])
+ })
+
+ it('a transaction that is retried counts its report once', async () => {
+ // The first attempt gets as far as its totals, then the commit fails: whatever it counted must be thrown away.
+ db.$transaction.mockImplementationOnce(async (fn: (tx: typeof db) => unknown) => { await fn(db); throw { code: 'P2034' } })
+ expect(await ingestProductUsage('a', report, now)).toEqual({ accepted: true })
+ expect(db.$transaction).toHaveBeenCalledTimes(2)
+ await flushRelayUsage()
+ expect(updates()).toEqual([['2026-10-13', 'turns_ended', 3], ['2026-10-13', 'turns_started', 4]])
+ })
+
+ it('a refused or already received report adds nothing', async () => {
+ choices({ userId: 'a', enabled: false, revision: 1 })
+ await ingestProductUsage('a', report, now)
+ db.productUsageReceipt.findMany.mockResolvedValue([{ id: report.id }])
+ await ingestProductUsage('a', report, now)
+ await flushRelayUsage()
+ expect(db.$runCommandRaw).not.toHaveBeenCalled()
+ })
+
+ it('keeps staff and testing totals apart in memory too', async () => {
+ accounts('[email protected]')
+ await ingestProductUsage('team', { ...report, id: 'r1' }, now)
+ await flushRelayUsage()
+ expect(updates().map(([, metric]) => metric)).toEqual(['staff:turns_ended', 'staff:turns_started'])
+ })
+})
+
describe('relay connects', () => {
const sent = (): Array<[string, string, number]> => db.$runCommandRaw.mock.calls.flatMap(([command]) =>
(command as { updates: Array<{ q: { dayUtc: { $date: string }; metric: string }; u: { $inc: { value: number } } }> }).updates
@@ -352,6 +433,8 @@ describe('relay connects', () => {
await flushRelayUsage()
expect(receipts()).toHaveLength(1)
expect(receipts()[0]).toMatch(/^relay:/)
+ // The receipt rule refuses a receipt without a life.
+ expect(db.productUsageReceipt.createMany.mock.calls[0][0].data[0].life).toBe(2)
expect(db.productUsageReceipt.createMany.mock.calls[0][0].data[0].expiresAt.getTime()).toBeGreaterThan(Date.now())
expect(db.$transaction).toHaveBeenCalledOnce()
})
@@ -578,6 +661,7 @@ it('setup ingestion never reads an account and expires after yesterday', async (
it('Hub totals share the setup path: unlinked receipt, atomic totals, a retried receipt counts once', async () => {
const hub = { id: report.id, day: report.day, counters: { hub_view_harness_visitor: 3, hub_fork: 1 } }
expect(await ingestSetupUsage(hub, now)).toEqual({ accepted: true })
+ await flushRelayUsage()
expect(db.productUsagePreference.findMany).not.toHaveBeenCalled()
expect(db.$runCommandRaw.mock.calls[0][0].updates).toEqual([
{ q: { dayUtc: { $date: '2026-10-13T00:00:00.000Z' }, metric: 'hub_view_harness_visitor' }, u: { $inc: { value: 3 } }, upsert: true },
diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.ts
index c9fc6d723..0b2572a65 100644
--- a/backend/src/lib/productUsage.ts
+++ b/backend/src/lib/productUsage.ts
@@ -119,15 +119,18 @@ async function ingestCounters(report: SetupUsageReport & { revision?: number; co
const writeUsage = createUsageBatch(commitReports)
-/** One transaction for a batch: each report's permission, its receipt and the batch's summed totals commit together;
- * a lost HTTP response can be retried with the same id, and a receipt already committed counts once. Write conflicts
- * now come only from another process's batch: the whole batch is retried, permission included, at most four
+/** One transaction for a batch: each report's permission and its receipt commit together; a lost HTTP response can be
+ * retried with the same id, and a receipt already committed counts once. The batch's totals are then added to this
+ * process's in-memory sums (`relayTotals`), which are written once a minute. A conflict with another process's
+ * batch retries the whole batch, permission included, at most four
* attempts, and only fast conflicts may start another within the first second. */
async function commitReports(reports: QueuedReport[]): Promise<IngestResult[]> {
const started = performance.now()
+ let counted: UsageIncrement[] = []
for (let attempt = 0; ; attempt++) {
+ counted = []
try {
- return await prisma.$transaction(async tx => {
+ const committed = await prisma.$transaction(async tx => {
const choices = await productUsageChoices([...new Set(reports.flatMap(r => r.userId ? [r.userId] : []))], tx)
const results: IngestResult[] = reports.map(r => {
const choice = r.userId ? choices.get(r.userId)! : null
@@ -147,10 +150,13 @@ async function commitReports(reports: QueuedReport[]): Promise<IngestResult[]> {
// [life]: once the receipt sweep's rule is installed, a server that does not write it cannot count (productUsageReceiptSweep.ts).
id: r.id, expiresAt: new Date(Date.parse(r.day) + PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS * DAY), life: PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS })) })
const apart = await apartPrefixes(tx, fresh)
- await incrementUsageTotals(tx, summed(fresh.flatMap((r, i) =>
- apart[i] ? r.increments.map(inc => ({ ...inc, metric: apart[i] + inc.metric })) : r.increments)))
+ counted = fresh.flatMap((r, i) => apart[i] ? r.increments.map(inc => ({ ...inc, metric: apart[i] + inc.metric })) : r.increments)
return results
})
+ // Counted after the commit, never inside an attempt that may be rolled back or retried. The receipt is already
+ // stored, so a report sent again counts nothing; a process that dies now loses under a minute of totals.
+ for (const inc of summed(counted)) relayTotals.add(inc.dayUtc, inc.metric, inc.value)
+ return committed
} catch (error) {
await pauseForConflict(error, attempt, started)
}
@@ -233,7 +239,8 @@ async function writeRelayBatch(id: string, increments: UsageIncrement[]): Promis
try {
return await prisma.$transaction(async tx => {
if ((await tx.productUsageReceipt.findMany({ where: { id: { in: [receipt] } }, select: { id: true } })).length) return
- await tx.productUsageReceipt.createMany({ data: [{ id: receipt, expiresAt: new Date(Date.now() + 2 * DAY) }] })
+ // [life]: the receipt rule (productUsageReceiptSweep.ts) refuses a receipt without one; this one lives 2 days.
+ await tx.productUsageReceipt.createMany({ data: [{ id: receipt, expiresAt: new Date(Date.now() + 2 * DAY), life: 2 }] })
await incrementUsageTotals(tx, increments)
})
} catch (error) {
@@ -242,6 +249,7 @@ async function writeRelayBatch(id: string, increments: UsageIncrement[]): Promis
}
}
+// Relay connects and report totals share one set of sums, so a counter is written at most once a minute per process.
const relayTotals = createRelayTotals({ write: writeRelayBatch })
export const flushRelayUsage = relayTotals.flush
/** Run in each process that takes connections. The stop it returns flushes what is waiting: call it on shutdown. */
diff --git a/backend/src/lib/productUsageRelay.test.ts b/backend/src/lib/productUsageRelay.test.ts
index 060e3270b..d8cff13a5 100644
--- a/backend/src/lib/productUsageRelay.test.ts
+++ b/backend/src/lib/productUsageRelay.test.ts
@@ -27,6 +27,16 @@ describe('relay totals', () => {
['2026-10-29', 'relay_machine_connections', 40], ['2026-10-29', 'relay_tui_opens', 300], ['2026-10-30', 'relay_tui_opens', 7]])
})
+ it('adds a counted value, so a report of 4 turns is one increment of 4 beside the connects', async () => {
+ const write = vi.fn<Write>(async () => {})
+ const totals = setup(write)
+ totals.add(day, 'turns_started', 4)
+ totals.add(day, 'turns_started', 8)
+ totals.add(day, 'relay_tui_opens')
+ await totals.flush()
+ expect(sorted(write.mock.calls[0][1])).toEqual([['2026-10-29', 'relay_tui_opens', 1], ['2026-10-29', 'turns_started', 12]])
+ })
+
it('writes nothing when nothing was counted', async () => {
const write = vi.fn<Write>(async () => {})
await setup(write).flush()
diff --git a/backend/src/lib/productUsageRelay.ts b/backend/src/lib/productUsageRelay.ts
index bb820393f..2012931d4 100644
--- a/backend/src/lib/productUsageRelay.ts
+++ b/backend/src/lib/productUsageRelay.ts
@@ -3,16 +3,16 @@ import type { UsageIncrement } from './productUsageWrite.js'
interface Batch { id: string; increments: UsageIncrement[]; attempts: number }
-/** Relay connects add to the same few daily totals, so one write per connect made the processes wait on one
- * another's rows (about 350 ms a write when they collided). Here a process counts in memory, keyed by day and
- * name only, and writes the sums once a minute.
+/** Relay connects and client reports add to the same few daily totals, so one write per event made the processes
+ * wait on one another's rows (about 350 ms a write when they collided) and cost the database a write per event.
+ * Here a process counts in memory, keyed by day and name only, and writes the sums once a minute.
*
* A batch has an id, and [write] must apply the batch and record that id together, doing nothing for an id it has
* seen. A batch that fails is held and sent again under the same id, so one whose answer was lost counts once.
* What a crash loses is what was counted since the last flush: under a minute. A clean stop flushes first.
* Bounded: past [maxKeys] waiting totals it flushes at once; past twice that, while the database is down, it drops
* new totals; a batch that failed [retries] times is dropped. Nothing here knows who connected. */
-export function createRelayTotals({ write, retries = 5, maxKeys = 1024, intervalMs = 60_000, newId = randomUUID, warn = console.warn,
+export function createRelayTotals({ write, retries = 5, maxKeys = 4096, intervalMs = 60_000, newId = randomUUID, warn = console.warn,
firstDelayMs = Math.floor(intervalMs * (0.5 + Math.random() / 2)) }: {
write: (id: string, increments: UsageIncrement[]) => Promise<void>
retries?: number; maxKeys?: number; intervalMs?: number; newId?: () => string; warn?: (message: string) => void
@@ -33,7 +33,7 @@ export function createRelayTotals({ write, retries = 5, maxKeys = 1024, interval
if (failed) {
const batch = failed
try { await write(batch.id, batch.increments); failed = null } catch {
- if (++batch.attempts >= retries) { failed = null; complain('[product-usage] Some relay counts were dropped after repeated write failures.') }
+ if (++batch.attempts >= retries) { failed = null; complain('[product-usage] Some counts were dropped after repeated write failures.') }
return
}
}
@@ -42,19 +42,19 @@ export function createRelayTotals({ write, retries = 5, maxKeys = 1024, interval
pending = new Map()
try { await write(batch.id, batch.increments) } catch {
failed = batch
- complain('[product-usage] Some relay counts are unavailable.')
+ complain('[product-usage] Some counts are unavailable.')
}
}
function flush(): Promise<void> {
return flushing ??= run().finally(() => { flushing = null })
}
- function add(dayUtc: Date, metric: string): void {
+ function add(dayUtc: Date, metric: string, value = 1): void {
const key = `${dayUtc.getTime()}|${metric}`
const seen = pending.get(key)
- if (seen) { seen.value++; return }
- if (pending.size >= maxKeys * 2) return complain('[product-usage] Some relay counts were dropped: too many waiting.')
- pending.set(key, { dayUtc, metric, value: 1 })
+ if (seen) { seen.value += value; return }
+ if (pending.size >= maxKeys * 2) return complain('[product-usage] Some counts were dropped: too many waiting.')
+ pending.set(key, { dayUtc, metric, value })
if (pending.size >= maxKeys) void flush()
}
diff --git a/backend/src/lib/productUsageWrite.ts b/backend/src/lib/productUsageWrite.ts
index af98cd7b9..aa39a27a2 100644
--- a/backend/src/lib/productUsageWrite.ts
+++ b/backend/src/lib/productUsageWrite.ts
@@ -7,11 +7,22 @@ export interface UsageIncrement { dayUtc: Date; metric: string; value: number }
* overlapping uploads to exhaust retries. No report body or identity becomes a stored document. */
export async function incrementUsageTotals(tx: Pick<Prisma.TransactionClient, '$runCommandRaw'>, increments: UsageIncrement[]): Promise<void> {
if (!increments.length) return
+ await runTotals(tx, increments, '$inc')
+}
+
+/** Sets each total to its value, in as few commands as fit: the hourly people rollup. Prisma's `upsert` on the
+ * compound key reads, then writes, each total; this is one command per [SET_CHUNK] totals and reads nothing. */
+export const SET_CHUNK = 500
+export async function setUsageTotals(db: Pick<Prisma.TransactionClient, '$runCommandRaw'>, totals: UsageIncrement[]): Promise<void> {
+ for (let i = 0; i < totals.length; i += SET_CHUNK) await runTotals(db, totals.slice(i, i + SET_CHUNK), '$set')
+}
+
+async function runTotals(tx: Pick<Prisma.TransactionClient, '$runCommandRaw'>, increments: UsageIncrement[], op: '$inc' | '$set'): Promise<void> {
const result = await tx.$runCommandRaw({
update: 'product_usage_totals', ordered: true,
updates: increments.map(({ dayUtc, metric, value }) => ({
q: { dayUtc: { $date: dayUtc.toISOString() }, metric },
- u: { $inc: { value } }, upsert: true,
+ u: { [op]: { value } }, upsert: true,
})),
})
// A command can return ok:1 with writeErrors. Never commit its receipt after a partial write.
diff --git a/backend/src/services/ProductUsagePeopleRollupService.test.ts b/backend/src/services/ProductUsagePeopleRollupService.test.ts
index 66b8c9e72..62841a28c 100644
--- a/backend/src/services/ProductUsagePeopleRollupService.test.ts
+++ b/backend/src/services/ProductUsagePeopleRollupService.test.ts
@@ -1,9 +1,10 @@
import { beforeEach, expect, it, vi } from 'vitest'
-const db = vi.hoisted(() => ({ productUsageActivity: { findMany: vi.fn() }, productUsageTotal: { upsert: vi.fn() } }))
+const db = vi.hoisted(() => ({ productUsageActivity: { findMany: vi.fn() }, productUsageTotal: { upsert: vi.fn(), findFirst: vi.fn(), findUnique: vi.fn() }, $runCommandRaw: vi.fn() }))
vi.mock('../lib/prisma.js', () => ({ prisma: db }))
import { rollupPeople } from './ProductUsagePeopleRollupService.js'
-beforeEach(() => { vi.resetAllMocks(); db.productUsageTotal.upsert.mockResolvedValue({}) })
+beforeEach(() => { vi.resetAllMocks(); db.$runCommandRaw.mockImplementation(async command => ({ ok: 1, n: command.updates.length })) })
+const sent = () => db.$runCommandRaw.mock.calls.flatMap(([command]) => command.updates as Array<{ q: { dayUtc: { $date: string }; metric: string }; u: unknown; upsert: boolean }>)
it('reads only the live window of marks and writes totals with $set, never $inc', async () => {
db.productUsageActivity.findMany.mockResolvedValue([
@@ -12,11 +13,9 @@ it('reads only the live window of marks and writes totals with $set, never $inc'
const written = await rollupPeople(new Date('2026-10-14T05:00:00Z'))
expect(db.productUsageActivity.findMany.mock.calls[0][0].where).toEqual({ dayUtc: { gte: new Date('2026-10-05') } })
expect(written).toBeGreaterThan(0)
- expect(db.productUsageTotal.upsert).toHaveBeenCalledWith({
- where: { dayUtc_metric: { dayUtc: new Date('2026-10-12'), metric: 'people_active' } },
- create: { dayUtc: new Date('2026-10-12'), metric: 'people_active', value: 1 }, update: { value: 1 },
- })
- expect(JSON.stringify(db.productUsageTotal.upsert.mock.calls)).not.toContain('"x"')
+ expect(sent()).toContainEqual({ q: { dayUtc: { $date: '2026-10-12T00:00:00.000Z' }, metric: 'people_active' }, u: { $set: { value: 1 } }, upsert: true })
+ expect(JSON.stringify(db.$runCommandRaw.mock.calls)).not.toContain('"x"')
+ expect(JSON.stringify(db.$runCommandRaw.mock.calls)).not.toContain('$inc')
})
it('reads the hosting mark and writes its total', async () => {
@@ -25,5 +24,17 @@ it('reads the hosting mark and writes its total', async () => {
])
await rollupPeople(new Date('2026-10-14T05:00:00Z'))
expect(db.productUsageActivity.findMany.mock.calls[0][0].select).toMatchObject({ hosting: true })
- expect(db.productUsageTotal.upsert).toHaveBeenCalledWith(expect.objectContaining({ create: { dayUtc: new Date('2026-10-12'), metric: 'people_hosting', value: 1 } }))
+ expect(sent()).toContainEqual({ q: { dayUtc: { $date: '2026-10-12T00:00:00.000Z' }, metric: 'people_hosting' }, u: { $set: { value: 1 } }, upsert: true })
+})
+
+it('writes every total in a few commands and reads nothing from the totals first', async () => {
+ db.productUsageActivity.findMany.mockResolvedValue([
+ { subject: 'x', dayUtc: new Date('2026-10-12'), surfaces: ['web'], worked: true, signupDay: new Date('2026-09-01'), staff: false },
+ ])
+ const written = await rollupPeople(new Date('2026-10-14T05:00:00Z'))
+ expect(sent()).toHaveLength(written)
+ expect(db.$runCommandRaw.mock.calls.length).toBe(Math.ceil(written / 500))
+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()
+ expect(db.productUsageTotal.findFirst).not.toHaveBeenCalled()
+ expect(db.productUsageTotal.findUnique).not.toHaveBeenCalled()
})
diff --git a/backend/src/services/ProductUsagePeopleRollupService.ts b/backend/src/services/ProductUsagePeopleRollupService.ts
index 5a13ee5a6..1361ab025 100644
--- a/backend/src/services/ProductUsagePeopleRollupService.ts
+++ b/backend/src/services/ProductUsagePeopleRollupService.ts
@@ -1,6 +1,7 @@
import { peopleCounters } from '../analytics/peopleCounters.js'
import { ACTIVITY_DAYS } from '../types/productUsageActivity.js'
import { prisma } from '../lib/prisma.js'
+import { setUsageTotals } from '../lib/productUsageWrite.js'
import { logger } from '../utils/logger.js'
const DAY = 86_400_000
@@ -16,10 +17,7 @@ export async function rollupPeople(now = new Date()): Promise<number> {
select: { subject: true, dayUtc: true, surfaces: true, worked: true, hosting: true, signupDay: true, staff: true },
})
const counters = peopleCounters(marks, now)
- for (const { day, metric, value } of counters) {
- const dayUtc = new Date(day)
- await prisma.productUsageTotal.upsert({ where: { dayUtc_metric: { dayUtc, metric } }, create: { dayUtc, metric, value }, update: { value } })
- }
+ await setUsageTotals(prisma, counters.map(({ day, metric, value }) => ({ dayUtc: new Date(day), metric, value })))
return counters.length
}
diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.ts
index 98eaf638e..d437a3837 100644
--- a/cli/src/lib/swarmSkills.spec.ts
+++ b/cli/src/lib/swarmSkills.spec.ts
@@ -217,9 +217,12 @@ describe('built-in Swarm skills', () => {
// right before the shared-machine rules, or before Requests and Done for each Lead; only the Lead adds 🚀 at a merge. A
// handoff such as "Ready for review" stays a post (Lead, 10-29): it opens the review.
const react = '- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.\n'
- const substance = '- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").\n'
+ // Task #3057 (Ken, 11-05): acknowledgements and status from an assignee in its own task still reached the PM. Never post an
+ // acknowledgement, react; status goes through work.status; name the PM only when you need it to act.
+ const post = '- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead.'
+ const substance = (role: 'lead' | 'dev' | 'review') => `${post}${role === 'lead' ? '' : ' Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.'}\n`
const rocket = '- When a group\'s pull request merges, react 🚀 to the message that assigned its work.\n'
- const reactions = (role: 'lead' | 'dev' | 'review') => `## Reactions\n${react}${substance}${role === 'lead' ? rocket : ''}\n`
+ const reactions = (role: 'lead' | 'dev' | 'review') => `## Reactions\n${react}${substance(role)}${role === 'lead' ? rocket : ''}\n`
// Before a section that is last: after a blank line, without its own.
const reactionsBefore = (role: 'lead' | 'dev' | 'review') => `\n${reactions(role).trimEnd()}\n`
// Who a post reaches (project instructions, phase 1): every role, in both modes, in a section of its own right before Reactions.
@@ -1006,8 +1009,8 @@ describe('a Buddy\'s folder', () => {
// Project instructions, phase 4 (decision 1): a session is a coordinator, an agent or a Buddy. Its role file stays the
// built-in text it launched with, for a Swarm with no instructions, and a row an older CLI saved relaunches onto its own.
describe('role kinds keep their role files', () => {
- /** The whole file a Reviewer's launch writes in each mode, byte for byte, as before role kinds (its post rules as of #2963). */
- const REVIEW = { orchestration: '4270fcbf17355c8df6a65c6977b70bcc6064c2d3210533dc99fdf3b16af5d2d9', default: '2704930e91c7861d47c95f1c19ec7383edf23220eb720bed09ab1acbe7d34034' }
+ /** The whole file a Reviewer's launch writes in each mode, byte for byte, as before role kinds (its post rules as of #3057). */
+ const REVIEW = { orchestration: '9238d7fd7a516bee7b5d64d4145e2a1fa9cb4e96c5d9a4cdddb5751cd346db98', default: 'd8cab4c0afa83e57a2975caeda63341ed839ba94c4ab56b35c138275e3ad22c2' }
const folder = (workspace: string, key: string, name: string) =>
join(realpathSync(workspace), '.harness', 'runtime', sha256(key), 'swarm', 'skills', name)
it('keeps each session\'s role file', () => {
diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.ts
index e78d0512e..eb3983c7c 100644
--- a/cli/src/lib/swarmSkills.ts
+++ b/cli/src/lib/swarmSkills.ts
@@ -168,7 +168,7 @@ For large work, post the group plan and get the owner's ok before assigning; onc
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead.
- When a group's pull request merges, react 🚀 to the message that assigned its work.
## Requests and Done
@@ -306,7 +306,7 @@ Record each acceptance check with the exact command, revision and observed resul
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead. Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.
## Shared machines and secrets
- Stop only processes and databases you started yourself, by the process id you recorded when you started them. Never stop anything by name or pattern (pkill -f, killall): on a shared machine that kills other agents' work.
@@ -384,7 +384,7 @@ Mark your review assignment done with the verdict and revision. Print little.
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead. Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.
## Shared machines and secrets
- Stop only processes and databases you started yourself, by the process id you recorded when you started them. Never stop anything by name or pattern (pkill -f, killall): on a shared machine that kills other agents' work.
@@ -493,7 +493,7 @@ When the project owner asks in chat to switch this project's skills (Default or
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead.
- When a group's pull request merges, react 🚀 to the message that assigned its work.
## Requests and Done
@@ -561,7 +561,7 @@ You finish one group's work completely, inside its brief, as if nobody will come
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead. Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.
## Shared machines and secrets
- Stop only processes and databases you started yourself, by the process id you recorded when you started them. Never stop anything by name or pattern (pkill -f, killall): on a shared machine that kills other agents' work.
@@ -612,7 +612,7 @@ Mark your review done with the verdict and revision.
## Reactions
- Acknowledge with a reaction instead of a post, as Slack bots do: react 👀 to a message addressed to you when you start on it; when you have done what it asked, take the 👀 back and react ✅. Use harness super-tab react GROUP MESSAGE_ID eyes|check OPERATION_ID, with --off to take one back. A reaction tells the people in the chat; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence; never an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead. Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.
## Shared machines and secrets
- Stop only processes and databases you started yourself, by the process id you recorded when you started them. Never stop anything by name or pattern (pkill -f, killall): on a shared machine that kills other agents' work.
diff --git a/cli/src/lib/swarmTools.spec.ts b/cli/src/lib/swarmTools.spec.ts
index 1f4347798..c30916077 100644
--- a/cli/src/lib/swarmTools.spec.ts
+++ b/cli/src/lib/swarmTools.spec.ts
@@ -27,6 +27,12 @@ describe('SWARM_TOOLS_SKILL', () => {
it('says an agent with work in the project posts in its chat without joining it', () => {
expect(SWARM_TOOLS_SKILL).toContain('In the project chat, an agent with a task or step in the project posts and reacts without joining it, and a person\'s answer to its line reaches it; `--to` there adds no agent, so name only the coordinator.')
})
+ // Task #3057 (Ken, 11-05): an assignee's "Confirmed: I have read the task" and progress notes in its own task still reached the PM.
+ it('says never to post an acknowledgement but react, status goes through work.status, name the PM only to act', () => {
+ const section = SWARM_TOOLS_SKILL.slice(SWARM_TOOLS_SKILL.indexOf('## Reactions'), SWARM_TOOLS_SKILL.indexOf('## Commands (JSON)'))
+ expect(section).toContain('Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead.')
+ expect(section).toContain('Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.')
+ })
// Task #2963 (Ken, 2026-11-04): 402 of 437 agent posts in a day reached the PM as their only recipient; 1 named it.
it('says a post reaches only who it names, a reply its author, an unnamed one in a task its assignee, and the coordinator by status', () => {
const at = SWARM_TOOLS_SKILL.indexOf('### Who a post reaches')
diff --git a/cli/src/lib/swarmTools.ts b/cli/src/lib/swarmTools.ts
index 1135c660d..dc62a1bda 100644
--- a/cli/src/lib/swarmTools.ts
+++ b/cli/src/lib/swarmTools.ts
@@ -45,7 +45,7 @@ Every command starts \`harness super-tab --tab TAB\` (your tab id is in your lau
## Reactions
- \`react GROUP MESSAGE_ID EMOJI OPERATION_ID [--off]\` acknowledges without a post, as Slack bots do. EMOJI: eyes (👀) when you start on a message addressed to you, check (✅) when you have done what it asked, rocket (🚀) when its work merged; also thumbs_up, tada, heart, laugh. \`--off\` takes yours back (take the 👀 back, then react ✅).
- A reaction tells the people in the chat and wakes nobody; your work status still tells the Swarm.
-- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement alone ("on it", "took it", "thanks", "done").
+- Post only substance: a plan, a question, a ruling, a finding, a verdict, a handoff, a blocker or a result with its evidence. Never post an acknowledgement ("on it", "took it", "confirmed", "thanks", "done"): react instead. Your status goes through work.status and your results to whoever asked for the work; name the PM with --to only when you need it to act.
## Commands (JSON)
\`command OPERATION_ID JSON\` sends one command. The JSON is one argument; when it holds quotes, put - in its place and send it on stdin:
diff --git a/cli/src/superTabs/deliveryContext.ts b/cli/src/superTabs/deliveryContext.ts
index 8c68188b0..9dde808cf 100644
--- a/cli/src/superTabs/deliveryContext.ts
+++ b/cli/src/superTabs/deliveryContext.ts
@@ -38,6 +38,15 @@ export function placeLine(state: Json, groupId: string): string {
const taskWords = (task: Json): string =>
`task ${typeof task.number === 'number' ? `#${task.number} ` : ''}${JSON.stringify(String(task.title ?? ''))}`
+/** Whether [authorId], the project's coordinator, wrote in a task or step [groupId] that [agentId] holds (task #3057, Ken 11-05).
+ * A post there that names no one reaches no agent, so the reader needs no --to to answer it; the delivery's sample reply
+ * command used to carry --to the sender, and agents copied it into their acknowledgements to the PM. */
+export function coordinatorInOwnTask(state: Json, groupId: string, authorId: string, agentId: string): boolean {
+ if (!isCoordinator(state, authorId)) return false
+ const group = list(state.conversations).find(c => c.id === groupId)
+ return !!group && (isStep(group) || typeof group.number === 'number') && object(group.assignment).agentId === agentId
+}
+
const and = (items: string[]): string => items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`
/** What the receiving agent itself works on: its open tasks, up to three; the coordinator's count of its project's. */
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index 2282aeece..e50200a2d 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -991,6 +991,50 @@ describe('Super Tab native delivery handoff', () => {
expect(prompt).toContain('In task #12 "Fix login" (conversation g12).\nYou are assigned task #12 "Fix login" (working).\n')
expect(prompt.indexOf('You are assigned')).toBeLessThan(prompt.indexOf('Message message from'))
})
+ // Task #3057 (Ken, 11-05): the reply line carried --to <sender>, and agents copied --to the PM into their own task, so
+ // 29 of 55 acknowledgements still reached it. In its own task or step a coordinator's message gets the plain form.
+ describe('the reply line to the coordinator in the reader\'s own task (#3057)', () => {
+ const PM = { kind: 'agent', id: 'pm', name: 'River' }
+ const STEP = { id: 'g13', projectId: 'app', number: 13, title: 'Review login', reviewOf: 'g12', step: 'review', leadId: 'pm', archived: false, assignment: { agentId: 'agent', status: 'working' } }
+ const replyLines = (prompt: string) => prompt.split('\n').filter(l => l.startsWith('Reply there: ') || l.startsWith('To acknowledge'))
+ it('shows the plain post form, with no --reply-to and no --to, and says to react to acknowledge', async () => {
+ const { t } = wired({ author: PM, text: 'Fern4, task #12 is yours: read it in full. Tests first.', thread: 'message' })
+ const lines = replyLines(await delivered(t))
+ expect(lines[0]).toContain("post 'g12' 'your message' UNIQUE_OPERATION_ID")
+ expect(lines[0]).not.toContain('--to')
+ expect(lines[0]).not.toContain('--reply-to')
+ expect(lines[0]).not.toContain('--answers')
+ expect(lines[0]).toContain('reaches no agent')
+ expect(lines[1]).toContain("react 'g12' 'message' eyes UNIQUE_OPERATION_ID")
+ })
+ it('does the same in a step the reader is assigned', async () => {
+ const swarm = { ...SWARM, conversations: [...SWARM.conversations, STEP] }
+ const { t } = wired({ conversationId: 'g13', author: PM, text: 'Review the pull request.', thread: 'message' }, {}, () => swarm)
+ const lines = replyLines(await delivered(t))
+ expect(lines[0]).not.toContain('--to')
+ expect(lines[0]).not.toContain('--reply-to')
+ expect(lines[1]).toContain('react')
+ })
+ it('keeps --reply-to and --to when the coordinator asks the reader a question', async () => {
+ const { t } = wired({ author: PM, text: 'Is the draft pull request open yet?', thread: 'message' })
+ const [line] = replyLines(await delivered(t))
+ expect(line).toMatch(/ --answers 'message' --to 'pm'$/)
+ })
+ it('keeps --reply-to in a thread when the coordinator asks the reader a question', async () => {
+ const { t } = wired({ author: PM, text: 'Which file is it in?', thread: 'root', replyTo: 'root' })
+ const [line] = replyLines(await delivered(t))
+ expect(line).toMatch(/ --reply-to 'message' --to 'pm'$/)
+ })
+ it('keeps the named form for an agent that is not the coordinator, a task the reader does not hold, and the project chat', async () => {
+ const reviewer = wired({ author: { kind: 'agent', id: 'rev', name: 'Rev1' }, text: 'Two findings.', thread: 'message' })
+ expect(replyLines(await delivered(reviewer.t))[0]).toMatch(/ --answers 'message' --to 'rev'$/)
+ const other = { ...SWARM, conversations: [SWARM.conversations[0]!, { ...SWARM.conversations[1]!, assignment: { agentId: 'someone', status: 'working' } }] }
+ const notMine = wired({ author: PM, text: 'FYI.', thread: 'message' }, {}, () => other)
+ expect(replyLines(await delivered(notMine.t))[0]).toMatch(/ --answers 'message' --to 'pm'$/)
+ const chat = wired({ conversationId: 'lead', author: PM, text: 'Hello.', thread: 'message' })
+ expect(replyLines(await delivered(chat.t))[0]).toMatch(/ --answers 'message' --to 'pm'$/)
+ })
+ })
it('a delivery whose read fails still goes, without its lines', async () => {
const { t } = wired({}, {}, () => { throw new Error('offline') })
const prompt = await delivered(t)
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index bc967f20a..65f4d6128 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -31,7 +31,7 @@ import { conversationTokens } from '../lib/conversationSize.js'
import { isTeamDaemon } from './teamDaemon.js'
import { HostFeed } from './hostFeed.js'
import { SwarmReads } from './swarmReads.js'
-import { placeLine, threadLine, workLine } from './deliveryContext.js'
+import { coordinatorInOwnTask, placeLine, threadLine, workLine } from './deliveryContext.js'
import { UPDATE_REQUIRED } from './readContract.js'
import { projectsRoot } from '../lib/projectFolder.js'
import { worktreeFolderName } from '../lib/agentNames.js'
@@ -439,6 +439,9 @@ const writeJournal = (file: string, journal: Journal) => {
renameSync(temporary, file)
}
+/** Whether a message asks its reader something: then the answer goes to the one who asked. */
+const asksQuestion = (text: unknown): boolean => typeof text === 'string' && text.includes('?')
+
/** The same rules the launch prompt gives (desktop/lib/super_tabs/launch.dart). On 2026-10-20 a Lead answered one
* question twice, once in a long technical report. */
const SUPER_TAB_REPLY_STYLE = 'Write to the people in this tab like a helpful colleague. Answer first, in plain words and in the language they used. '
@@ -493,6 +496,8 @@ export class SuperTabHost {
private readonly quotes = new Map<string, string>()
/** Each delivery's context lines (deliveryContext.ts), read once per delivery and kept while it is tried again. */
private readonly contexts = new Map<string, string>()
+ /** Deliveries whose message is the coordinator's in the reader's own task or step, with no question to answer (#3057). */
+ private readonly plainReplies = new Set<string>()
/** The one-message page `repliedTo()` read, for the thread line when the reply answers its thread's root. */
private readonly replyPages = new Map<string, Json>()
private readonly active = new Set<string>()
@@ -1281,7 +1286,7 @@ export class SuperTabHost {
for (const deliveryId of this.files.keys()) if (!this.journal.entries[deliveryId]) this.files.delete(deliveryId)
for (const deliveryId of [...this.downloads.keys()]) if (!this.journal.entries[deliveryId]) this.dropDownload(deliveryId)
for (const deliveryId of this.quotes.keys()) if (!this.journal.entries[deliveryId]) this.quotes.delete(deliveryId)
- for (const deliveryId of this.contexts.keys()) if (!this.journal.entries[deliveryId]) this.contexts.delete(deliveryId)
+ for (const deliveryId of this.contexts.keys()) if (!this.journal.entries[deliveryId]) { this.contexts.delete(deliveryId); this.plainReplies.delete(deliveryId) }
for (const deliveryId of this.replyPages.keys()) if (!this.journal.entries[deliveryId]) this.replyPages.delete(deliveryId)
for (const entry of Object.values(this.journal.entries)) {
const id = typedId(entry)
@@ -2213,6 +2218,9 @@ export class SuperTabHost {
const read = await within(this.sources.reads.read(entry.tabId, entry.agentId), wait)
if (!read) throw new Error(`no answer in ${wait} ms`)
const { state } = read
+ const author = object(message.author)
+ if (author.kind === 'agent' && identifier(author.id) && !asksQuestion(message.text)
+ && coordinatorInOwnTask(state, group, author.id, entry.agentId)) this.plainReplies.add(entry.deliveryId)
lines.push(placeLine(state, group))
const work = workLine(state, entry.agentId)
if (work) lines.push(work)
@@ -2275,15 +2283,26 @@ export class SuperTabHost {
const native = source.kind === 'native'
? `This is an observed native ${String(source.phase)} in ${shownName(message.author, 'an agent')}’s terminal, opened by ${shownName(source.operator, 'a collaborator')}. The input already reached that agent. Keep the shared work coordinated; do not replay the same instruction.\n\n`
: ''
- // A reply to an agent names it: a backend from before #2963 delivered an unnamed reply to the coordinator instead of its
- // author (final review). A person reads the chat itself.
+ // A post that names no one reaches no agent, except in a task or step, where it reaches the agent assigned there unless
+ // that is the poster (#2963, #3038). So --to is for an agent that must act or answer; the coordinator is named only when it
+ // is needed, and the reader's status (work.status) is how it hears the work. A reply to an agent that asked something is
+ // named with --to (a backend from before #2963 delivered an unnamed reply to the coordinator instead). A person reads the
+ // chat itself.
const author = object(message.author)
const to = author.kind === 'agent' && identifier(author.id) ? ` --to ${shellQuote(author.id)}` : ''
// A thread reply is answered in its thread, and a Buddy session's thread stays its own; any other message right below it.
const threaded = (identifier(message.thread) && message.thread !== message.id) || message.buddySession === true
+ // Task #3057 (Ken, 11-05): 29 of 55 agent posts to the PM still did not name it, mostly an assignee writing in its own task,
+ // because this line carried --to <sender> and the PM sends the briefs. The coordinator's message in the reader's own task or
+ // step, with no question, shows the plain form: in a task it reaches no agent, and the people see it. To acknowledge, react.
+ const plain = this.plainReplies.has(entry.deliveryId)
+ const replyLine = plain
+ ? `Reply there: ${command} post ${shellQuote(group)} 'your message' UNIQUE_OPERATION_ID (a post here reaches no agent, and the people see it; name no one unless you need them to act)\n`
+ + `To acknowledge, react instead of posting: ${command} react ${shellQuote(group)} ${shellQuote(String(message.id))} eyes UNIQUE_OPERATION_ID. Your status tells the PM your work.\n`
+ : `Reply there: ${command} post ${shellQuote(group)} 'your message' UNIQUE_OPERATION_ID ${threaded ? '--reply-to' : '--answers'} ${shellQuote(String(message.id))}${to}\n`
return `You are participating in a shared Super Tab conversation (${group}). Other humans and agents see messages posted there.\n`
+ `Read its state: ${command} status\nRead this conversation: ${command} messages ${shellQuote(group)}\n`
- + `Reply there: ${command} post ${shellQuote(group)} 'your message' UNIQUE_OPERATION_ID ${threaded ? '--reply-to' : '--answers'} ${shellQuote(String(message.id))}${to}\n`
+ + replyLine
+ `Manage agreed work and delegation: ${command} help.\n`
+ `Ask questions and post results in this conversation. ${SUPER_TAB_REPLY_STYLE} Replies to these delivered instructions must be posted here explicitly.\n\n`
+ context + native + reply + said
diff --git a/docs/plans/2026-11-05-usage-counters-minute-plan.md b/docs/plans/2026-11-05-usage-counters-minute-plan.md
new file mode 100644
index 000000000..6b8bd999f
--- /dev/null
+++ b/docs/plans/2026-11-05-usage-counters-minute-plan.md
@@ -0,0 +1,19 @@
+# Usage counters write once a minute — Plan
+
+**Goal:** Cut `product_usage_totals` load: no read before write, and each counter written at most once a minute per pod.
+**Architecture:** One in-memory accumulator per pod (`createRelayTotals`, already flushing relay connects every minute, with a receipt per batch) now also takes report totals; the hourly people rollup stops using Prisma `upsert` (find + update per counter) and sends one raw `$set` upsert command.
+**Tech Stack:** Fastify backend, Prisma on MongoDB, `$runCommandRaw`, vitest.
+**Spec:** Task #3052 (Ken, Watch Production: Atlas primary CPU ≤ 40% at peak).
+
+## Global Constraints
+- No new settings or switches. Counter names, meanings and UTC day boundary unchanged.
+- A report's receipt still commits in its transaction; only its totals wait in memory (a dead pod loses < 1 minute).
+- Totals are added to memory only after the transaction commits, never inside a retried attempt.
+
+## Review Focus
+- Double counting on transaction retry; flush on shutdown; the `Prisma upsert` fallback (compound unique) in the rollup.
+
+## Tasks
+- [ ] 1. `createRelayTotals.add(day, metric, value = 1)` (`backend/src/lib/productUsageRelay.ts`): test sums values, one write per key.
+- [ ] 2. Report ingest counts in memory after commit (`backend/src/lib/productUsage.ts`): tests — N reports → zero `product_usage_totals` writes in the transaction, one write per counter at flush, day boundary splits, retry counts once.
+- [ ] 3. Rollup writes one raw `$set` upsert command, no reads (`ProductUsagePeopleRollupService.ts`, `productUsageWrite.ts`): test — zero `upsert`/`find` on totals, chunks of 500.