diff --git a/.plans/README.md b/.plans/README.md index 970b260..c5c473f 100644 --- a/.plans/README.md +++ b/.plans/README.md @@ -4,6 +4,7 @@ Handoff from the September 11, 2026 discussion. These are small implementation b ## Remaining work +- [Update freshness and notification noise](update-freshness-and-notification-noise.md): use normal npm caching at startup; notification filtering and batching remain deferred. - [Setup and release work order](setup-and-release.md): Windows validation first, a Codex-in-T3 setup wizard, automatic worker updates, and nightly/stable releases. - [T3-only MCP registration](t3-only-mcp.md): keep the tools out of ordinary Codex sessions through configuration. - [npm distribution](npm-distribution.md): install and launch without a source checkout. Publication was deferred until real-world testing is satisfactory. diff --git a/.plans/npm-distribution.md b/.plans/npm-distribution.md index e76189d..a5072d5 100644 --- a/.plans/npm-distribution.md +++ b/.plans/npm-distribution.md @@ -7,12 +7,12 @@ Status: release infrastructure implemented after installer and platform verifica Users register MCP without cloning a repository, choosing a code directory, or building TypeScript. Once a package is published, the launch entry can use: ```text -npx --yes --prefer-online t3poll@latest mcp +npx --yes t3poll@latest mcp ``` This is a proposed invocation. Confirm the available npm package name and publishing account first; use a scope if needed. Follow [T3-only registration](t3-only-mcp.md) when configuring Codex. -`@latest` with an online check picks up stable releases when MCP launches. Offer `@nightly` as an explicit opt-in and preserve the selected channel. Ordinary installations should follow their channel rather than pinning the version used for setup. An explicit version can remain a troubleshooting option. +`@latest` follows stable releases when MCP launches, using npm's normal cache behavior. Offer `@nightly` as an explicit opt-in and preserve the selected channel. Ordinary installations should follow their channel rather than pinning the version used for setup. An explicit version can remain a troubleshooting option. Publish nightly builds automatically after checks. Trigger stable publication manually from a commit already shipped on nightly, following T3 Code's manual promotion approach. A channel change does not update an already-running MCP process or detached worker. Include [worker updates](worker-updates.md) in the release work so active monitoring survives version handoff. diff --git a/.plans/update-freshness-and-notification-noise.md b/.plans/update-freshness-and-notification-noise.md new file mode 100644 index 0000000..d7cb311 --- /dev/null +++ b/.plans/update-freshness-and-notification-noise.md @@ -0,0 +1,48 @@ +# Update freshness and notification noise + +Status: startup cache simplification approved and implemented after release 0.1.1. Notification changes remain deferred proposals. + +## Startup update checks + +The installer currently registers the equivalent of: + +```sh +npx --yes t3poll@latest mcp +``` + +Nightly installations use `@nightly`. The actual configuration invokes Node and npm by absolute path for reliable launching across platforms. `list` is a manual way to load a channel and initiate worker handoff; it is not the registered MCP command. + +`--yes` suppresses npm's package-install confirmation. It does not force a fresh download or answer the setup wizard's questions. `--prefer-online` forces cache freshness checks even when npm would otherwise reuse cached information. Existing MCP processes do not periodically query the registry. + +Decision: remove `--prefer-online` from newly generated MCP commands and accept npm's default cache behavior. Keep following the selected release channel. Existing launch configurations retain the flag until setup is rerun. Explicit manual update commands can still use `--prefer-online`. + +A possible later alternative is a bounded check interval with a working cached runtime as fallback. Decide the freshness interval and offline behavior before implementing that alternative. + +Reference: [npm exec flags and caching](https://docs.npmjs.com/cli/v11/commands/npm-exec/). + +## Notification observations + +During PR #7 babysitting, several wakeups only revealed another successful platform check while Windows or code review was still pending. The wakeup that exposed the candidate handoff timeout was useful and led to a fix. Review completion, including completion without findings, is useful for deciding when to merge. A notification already submitted to T3 can still arrive after the watch is stopped. + +Current sources of noise in `src/github.ts` and `src/model.ts`: + +- Any change to a bot comment's body counts, including summary timestamps, run IDs, and review-started or review-running edits. +- Our own pushes generate head-change notifications. +- Check fingerprints include run IDs, so another run can generate activity even when its conclusion is unchanged. CI currently runs for both pushes and pull requests; consider their overlap when evaluating duplicate results. +- Each wakeup says only "New activity", requiring a GitHub fetch to determine whether action is needed. + +Resolving a review thread does not directly trigger a notification because resolution state is not tracked. A subsequent bot-comment edit could trigger one indirectly. + +The store retains the current snapshot and latest delivery, not a full record of the changes behind each notification. The discussion assessed observed wakeups; it was not an exact historical audit of every trigger. + +## Proposed follow-up + +1. Notify promptly about new feedback and newly failing checks. +2. Aggregate successful checks into a useful completion notification instead of waking the agent for every platform. Define which checks constitute completion and how reruns affect it. +3. Preserve review-completion notifications, including reviews with no findings, while suppressing routine running-status edits. Distinguish meaningful edited feedback from bot summary churn. +4. Include a short, controlled reason such as "New review finding" or "All CI checks passed". Avoid copying arbitrary comment bodies into wakeups. +5. Consider short batching windows and deduplication for related review comments, review submissions, summary edits, and repeated check outcomes. +6. Evaluate whether self-originated pushes need a wakeup. Do not blanket-ignore bots or all activity from the authenticated GitHub account, since both can contain useful feedback. +7. Consider bounded diagnostic history recording trigger types and delivery IDs, so future notification audits can identify why each wakeup happened without retaining credentials or full comment bodies. + +Preserve failures, meaningful feedback edits, completed reviews, and merge/closure notifications while reducing wakeups that cannot change the agent's next action. Measure the result against a babysitting session with multiple platforms, reruns, and bot summary edits before choosing defaults. diff --git a/docs/updates.md b/docs/updates.md index 2b38cd1..7a07a0e 100644 --- a/docs/updates.md +++ b/docs/updates.md @@ -1,6 +1,6 @@ # Updates -Setup follows the invoked package's channel. New Codex sessions run npm with `--prefer-online` to resolve `latest` or `nightly`. Publishing alone does not change a running session. To load a channel now and hand over active watches, run: +Setup follows the invoked package's channel. New Codex sessions use npm's normal cache behavior to resolve `latest` or `nightly`, without forcing a freshness check at every startup. Publishing alone does not change a running session. To explicitly check for a newer package and hand over active watches, run: ```sh npx --yes --prefer-online t3poll@nightly list diff --git a/src/installer.ts b/src/installer.ts index f8203c4..5735641 100644 --- a/src/installer.ts +++ b/src/installer.ts @@ -71,7 +71,6 @@ function runtime(local: string | undefined): { npmCli(), "exec", "--yes", - "--prefer-online", `--package=t3poll@${releaseChannel(pkg.version)}`, "--", "t3poll",