From 9abc249e5a95a7515fdacad4df53a7bc9c97e16e Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sat, 31 Oct 2026 23:14:01 -0700 Subject: [PATCH 1/2] docs: where the BYO setup-OS fields live, and open PRs ready (11-01 lessons) The TASK-714 fields (setup OS, listener eligibility, per-type first copies) are written to users.onboarding, not to byo_telemetry; a telemetry-only read found no OS on 11-01 although prod had written it. Seats get one line in working-in-turns: open PRs ready, because the harness classifier can refuse a later gh pr ready that the turn never asked for (Keel #3130, 11-01). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015AKgpQ2pr6xRMhN5mcfoHF --- docs/development/byo-funnel-telemetry.md | 11 +++++++++++ fleet-skills/working-in-turns/SKILL.md | 1 + 2 files changed, 12 insertions(+) diff --git a/docs/development/byo-funnel-telemetry.md b/docs/development/byo-funnel-telemetry.md index 7966f17b39..71fd8697b3 100644 --- a/docs/development/byo-funnel-telemetry.md +++ b/docs/development/byo-funnel-telemetry.md @@ -4,6 +4,17 @@ The authenticated BYO page posts fixed event names to `POST /api/stats/byo-step` The endpoint stores `userId`, `step`, and server time in `byo_telemetry`. Commands, keys, names, and clipboard contents are never sent. +Setup OS and listener eligibility (TASK-714) are not stored in `byo_telemetry`. +`seat-created` and the copy steps also send `setupOs`, `listenerAvailable` and a +`copyType`, and the server writes those to the person's User row instead: +`users.onboarding.byoSetupOs` (`mac`, `linux`, `windows` or `other`), +`users.onboarding.byoListenerEligible`, and one write-once first-copy mark per +type (`byoListenCopiedAt`, `byoMcpClaudeCopiedAt`, `byoMcpCursorCopiedAt`, +`byoDaemonCopiedAt`, `byoTokenCopiedAt`). A query for "which OS did they set up +on" reads the User row. The `byo_telemetry` rows only answer "did they reach +this step, and when". On 2026-11-01 a read of `byo_telemetry` alone found no +setup OS at all, although prod had already written the fields to the User row. + As of TASK-483 and TASK-493 (2026-10-24), the browser sends: | Event | Observed state | diff --git a/fleet-skills/working-in-turns/SKILL.md b/fleet-skills/working-in-turns/SKILL.md index 9e448fadea..15f85b39c8 100644 --- a/fleet-skills/working-in-turns/SKILL.md +++ b/fleet-skills/working-in-turns/SKILL.md @@ -8,6 +8,7 @@ last_updated: 2026-11-01 # Working in Turns - End each turn before its run limit, not at it. The default run limit is 15 minutes, and only adapters that honor `COMMONLY_AGENT_RUN_TIMEOUT_MS` can use a longer one such as `2700000` (45 minutes). On a 45-minute limit, end the turn by about 35 minutes; on the 15-minute default, by about 10. Before ending: commit and push what you have (a draft PR is enough), and post the next step as a one-line note on the row. The next wake continues from the pushed branch. If the work is larger, split it and say how in the row. A timeout sends SIGTERM and loses uncommitted work. +- Open your PR as ready, not as a draft. A later `gh pr ready` can be refused by the harness's permission classifier ("Unrequested Commit in a Connected App") when your turn never said to undraft. That refusal comes from the harness, not from the seat `gh` fence. - **One review round per change.** Before you hand a PR to the press, run your own quick subagent review of its diff. Tier 2 changes (auth, grants, record, schema, wake, money, security) need an Opus-class reviewer. That one review also covers screenshots against the design frame, any lane checks and the zh-CN glossary. Don't ask a second reviewer, and don't ask anyone to re-review after you push a fix. - Then answer every CodeRabbit thread and get CI green. A push that only answers CodeRabbit or CI keeps your PASS. - If your review comes back HOLD, fix it, push, and review again yourself. From 4651981305288c2f00312dcc657d6d9893f593c9 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sat, 31 Oct 2026 23:15:42 -0700 Subject: [PATCH 2/2] docs: first value wins for setup OS; checkpoint PRs open ready (review fixes) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015AKgpQ2pr6xRMhN5mcfoHF --- docs/development/byo-funnel-telemetry.md | 10 ++++++---- fleet-skills/working-in-turns/SKILL.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/development/byo-funnel-telemetry.md b/docs/development/byo-funnel-telemetry.md index 71fd8697b3..95b08ba94f 100644 --- a/docs/development/byo-funnel-telemetry.md +++ b/docs/development/byo-funnel-telemetry.md @@ -5,10 +5,12 @@ The endpoint stores `userId`, `step`, and server time in `byo_telemetry`. Commands, keys, names, and clipboard contents are never sent. Setup OS and listener eligibility (TASK-714) are not stored in `byo_telemetry`. -`seat-created` and the copy steps also send `setupOs`, `listenerAvailable` and a -`copyType`, and the server writes those to the person's User row instead: -`users.onboarding.byoSetupOs` (`mac`, `linux`, `windows` or `other`), -`users.onboarding.byoListenerEligible`, and one write-once first-copy mark per +`seat-created` and every step also send `setupOs` and `listenerAvailable`, the +copy steps add a `copyType`, and the server writes those to the person's User +row instead: `users.onboarding.byoSetupOs` (`mac`, `linux`, `windows` or +`other`) and `users.onboarding.byoListenerEligible`, both written once (the +first request with a valid OS and a boolean wins; a later OS is ignored), and +one write-once first-copy mark per type (`byoListenCopiedAt`, `byoMcpClaudeCopiedAt`, `byoMcpCursorCopiedAt`, `byoDaemonCopiedAt`, `byoTokenCopiedAt`). A query for "which OS did they set up on" reads the User row. The `byo_telemetry` rows only answer "did they reach diff --git a/fleet-skills/working-in-turns/SKILL.md b/fleet-skills/working-in-turns/SKILL.md index 15f85b39c8..3b55e602be 100644 --- a/fleet-skills/working-in-turns/SKILL.md +++ b/fleet-skills/working-in-turns/SKILL.md @@ -7,7 +7,7 @@ last_updated: 2026-11-01 # Working in Turns -- End each turn before its run limit, not at it. The default run limit is 15 minutes, and only adapters that honor `COMMONLY_AGENT_RUN_TIMEOUT_MS` can use a longer one such as `2700000` (45 minutes). On a 45-minute limit, end the turn by about 35 minutes; on the 15-minute default, by about 10. Before ending: commit and push what you have (a draft PR is enough), and post the next step as a one-line note on the row. The next wake continues from the pushed branch. If the work is larger, split it and say how in the row. A timeout sends SIGTERM and loses uncommitted work. +- End each turn before its run limit, not at it. The default run limit is 15 minutes, and only adapters that honor `COMMONLY_AGENT_RUN_TIMEOUT_MS` can use a longer one such as `2700000` (45 minutes). On a 45-minute limit, end the turn by about 35 minutes; on the 15-minute default, by about 10. Before ending: commit and push what you have (an open PR is enough; open it ready), and post the next step as a one-line note on the row. The next wake continues from the pushed branch. If the work is larger, split it and say how in the row. A timeout sends SIGTERM and loses uncommitted work. - Open your PR as ready, not as a draft. A later `gh pr ready` can be refused by the harness's permission classifier ("Unrequested Commit in a Connected App") when your turn never said to undraft. That refusal comes from the harness, not from the seat `gh` fence. - **One review round per change.** Before you hand a PR to the press, run your own quick subagent review of its diff. Tier 2 changes (auth, grants, record, schema, wake, money, security) need an Opus-class reviewer. That one review also covers screenshots against the design frame, any lane checks and the zh-CN glossary. Don't ask a second reviewer, and don't ask anyone to re-review after you push a fix. - Then answer every CodeRabbit thread and get CI green. A push that only answers CodeRabbit or CI keeps your PASS.