cozyclay 3.2.0 → 3.2.1

package/tools/dev/pages/privacy.html

@@ -87,7 +87,7 @@ cclay telemetry on</code></pre>
             <tbody>
               <tr><td>install:first_launch, app:session_started, app:session_ended</td><td>Counting installs and sessions; duration and action counts are bucketed. install:first_launch may carry heard_from (x, hn, reddit, github, friend, other, site or playground), from the first-launch prompt or a copied <code>npx cozyclay --via</code> command. app:session_ended also carries scenes_touched (how many scenes were created or loaded in the session, an exact count capped at 20, not bucketed), session_id (the opaque random session id the PostHog SDK generates, used only to join a session's last events, such as an error just before it ended) and per-session edit gesture counts in five groups, pose_edit_bucket, camera_edit_bucket, object_edit_bucket, shot_edit_bucket and prompt_edit_bucket, each bucketed (0, 1-3, 4-10 or gte11); never what was edited</td></tr>
               <tr><td>app:friction_summary</td><td>Once per session, next to app:session_ended: how much friction the session had, as closed buckets only. active_time (the session duration bucket); counts of refusals the Studio gave the user (refusals_ui) and the agent (refusals_agent), user undos (undos), errors (errors), browser long tasks (long_tasks) and motion compiles (compiles), each as 0, 1, 2, 3, 4-5, 6-10 or gte11; the longest long task (long_task_max: lt50, 50-150, 150-500, 500-2000 or gte2000 ms); the share of late playback ticks (late_tick_ratio: 0, lt5, 5-20, 20-50 or gte50 %). rage_clicks and dead_clicks count every ui:rage_click and ui:dead_click, shortcut_ignored every shortcut:ignored, search_empty every search:no_results, and nav_thrash and camera_thrash every nav:thrash and camera:thrash, including those past their event's cap. Never which command, control, key or text was involved.</td></tr>
-              <tr><td>studio:refused</td><td>A command the Studio refused, as closed values only: code (one of the Studio's fixed error codes, such as INVALID_ARGUMENT, STALE_SCENE or TARGET_BUSY, else other), origin (ui for the user's own control, agent for the agent or an MCP client), phase (admission, refused before any change, or commit, refused after it started changing) and group (the command's family: object, shot, cast, scene, motion, edit, task, agent or other). At most 3 per code, group and origin per session; the rest are only counted in app:friction_summary. A cancel the caller asked for is not a refusal. Never the command's arguments, target or message.</td></tr>
+              <tr><td>studio:refused</td><td>A command the Studio refused, as closed values only: code (one of the Studio's fixed error codes, such as INVALID_ARGUMENT, STALE_SCENE or TARGET_BUSY, else other), origin (ui for the user's own control, agent for the agent or an MCP client), phase (admission, refused before any change, or commit, refused after it started changing) group (the command's family: object, shot, cast, scene, motion, edit, task, agent or other) and command (the refused action's id, such as object.set or shot.setCameraRail, only when it is one of the actions the Studio itself declares; a name the caller made up is left out). At most 3 per code, command (or group, without one) and origin per session; the rest are only counted in app:friction_summary. A cancel the caller asked for is not a refusal. Never the command's arguments, target or message.</td></tr>
               <tr><td>edit:undone</td><td>A user undo (agent undos are not counted): age (lt2s, 2-10s, 10-60s or gte60s since the undone edit was made, only when the undo was done and its age is known), kind (pose, camera, object, shot, prompt, agent_turn for the agent's whole turn, ik_preview for an un-applied IK drag, or other), via (key, menu or button) and result (done, noop when there was nothing to undo, or refused). At most 20 per session. Never what was undone.</td></tr>
               <tr><td>agent:turn_summary</td><td>One per agent turn: turn_id (the same random id as agent:turn_*); outcome (succeeded, failed or cancelled); wall (the turn's length) and first_tool (time to the first tool call, absent without tools), each lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m; counts of tool calls (tool_calls), failed tool calls (tool_failed), tool calls the Studio refused (refused), commands re-sent once after a stale revision or a busy gesture (stale_retry) and motion compiles (drafts), each as 0, 1, 2, 3, 4-5, 6-10 or gte11; refusal_top (the most frequent refusal code, or none); authored (true or false: the turn changed the scene); qa_first and qa_last (clean or problems, absent without drafts); qa_trend (improved, flat, worse, or na with fewer than 2 drafts); stuck (true or false: the motion compiler's stop rule fired); cancel_phase (before_tool, during_tool, after_tool or na). No prompt text, tool names, messages or responses.</td></tr>
               <tr><td>agent:post_turn_edit</td><td>One per agent turn: turn_id (the same random id) and the user's own edit gestures in the 120 seconds after the turn ended, closed early when the next turn starts or the page closes. edited (true or false); counts per group (pose, camera, object, shot, and prompt_block, which counts edits to a take's prompt and take fields), each as 0, 1, 2, 3, 4-5, 6-10 or gte11, where one continuous drag is one gesture; first_delay (time to the first edit: lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m), only when edited is true. Never which object or what changed.</td></tr>
@@ -103,7 +103,7 @@ cclay telemetry on</code></pre>
               <tr><td>agent:connect_finished</td><td>That attempt ended: provider, method, outcome (ok, failed, cancelled with the Cancel button, abandoned when closed or left unfinished), step it had reached (list, prompt, waiting or done) and duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m). Never the key, token, account, email or error text.</td></tr>
               <tr><td>agent:model_changed</td><td>A model picked in the agent's model list: its provider (as above, or other) and after_failure (whether the last agent turn had failed). At most 10 per session.</td></tr>
               <tr><td>agent:prompt_sent</td><td>One per prompt sent to the agent: turn_id (the same random id as agent:turn_*); provider (as for agent:connect_started, or other); via (typed, retry_button, regenerate, chip or supervisor); prompt_len (1-20, 21-80, 81-240 or gte241 characters); compose_ms (first keystroke to send, typed prompts only) and gap (since the previous turn ended, or first) as lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m; similarity (first, same, near or different, computed in the browser against the previous prompt's words); prev_outcome (succeeded, failed, cancelled or none); turn_index (1, 2, 3, 4-5, 6-10 or gte11); attached and task_mode (true or false). Never the prompt text or its words.</td></tr>
-              <tr><td>ui:rage_click</td><td>Three or more fast clicks (within 1 second and 24 pixels) on one primary control: control (a control id from a fixed list, such as tl_play or export_video, or other), clicks (3, 4-5 or gte6) and changed (whether the Studio responded within half a second). At most 2 per control per session. No coordinates, no text, no element or object ids.</td></tr>
+              <tr><td>ui:rage_click</td><td>Three or more fast clicks (within 1 second and 24 pixels) on one primary control: control (a control id from a fixed list, such as tl_play or export_video; for a control not on that list, the Studio area it sits in: other_guide, other_agent, other_menu, other_sculpt, other_assets, other_board, other_timeline, other_inspector or other_viewport; else other), clicks (3, 4-5 or gte6) and changed (whether the Studio responded within half a second). At most 2 per control per session. No coordinates, no text, no element or object ids.</td></tr>
               <tr><td>ui:dead_click</td><td>A click on a primary control that did nothing: control (as above) and reason (aria_disabled when the control was disabled, refused when the Studio refused the command, no_effect when nothing changed within half a second). At most 2 per control per session. Clicks into text fields are never observed.</td></tr>
               <tr><td>feature:used</td><td>One signal per feature per session: a fixed feature name such as pose_edit (a real bone or pose change), pose_save (saving a pose to the library), camera_fly, export_video, export_storyboard or export_render_pass</td></tr>
               <tr><td>$pageview, scene:created, scene:loaded, craft:first_action, activation:completed</td><td>Funnel and drop-off analysis</td></tr>
@@ -115,14 +115,15 @@ cclay telemetry on</code></pre>
               <tr><td>workflow:result_applied</td><td>Captured or generated image/video output was written to the Workflow canvas: run_id only, at most once per run, independently of a later failure. No image bytes or output contents.</td></tr>
               <tr><td>agent:turn_requested</td><td>Explicit Agent turn requests from surface (studio or workflow), paired by ephemeral turn_id. No prompts, responses or model identifiers.</td></tr>
               <tr><td>agent:tool_executed</td><td>Agent tool observations: turn_id, tool_category (workflow_read, workflow_write, workflow_run, frame_capture, image_generate, scene_write or other), outcome (succeeded, failed or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Tool names, arguments and results are excluded.</td></tr>
-              <tr><td>agent:turn_succeeded, agent:turn_failed, agent:turn_cancelled</td><td>Agent turn outcomes: turn_id and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s); failures and actual cancellations also include failure_code (aborted, auth, rate_limited, tool_failed, upstream, key_refused, stale_scene, capability_missing, busy, invalid_request or unknown). auth means CozyClay's local agent has no sign-in or refused the session; key_refused means the model provider rejected the key or credentials; stale_scene means the turn was refused because the scene changed underneath it; capability_missing means a required capability was unavailable, for example the live hub port was already in use; busy means another turn or target was busy; invalid_request means the request itself was rejected. Missing terminal delivery is not success.</td></tr>
+              <tr><td>agent:turn_succeeded, agent:turn_failed, agent:turn_cancelled</td><td>Agent turn outcomes: turn_id and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s); failures and actual cancellations also include failure_code (aborted, auth, rate_limited, tool_failed, upstream, network, key_refused, stale_scene, capability_missing, busy, invalid_request or unknown). upstream means the model provider failed (an HTTP 5xx, overload or a cut-off stream); network means the request never got an HTTP answer (offline, connection reset or DNS); unknown is any other failure. auth means CozyClay's local agent has no sign-in or refused the session; key_refused means the model provider rejected the key or credentials; stale_scene means the turn was refused because the scene changed underneath it; capability_missing means a required capability was unavailable, for example the live hub port was already in use; busy means another turn or target was busy; invalid_request means the request itself was rejected. Missing terminal delivery is not success.</td></tr>
               <tr><td>agent:result_applied</td><td>An Agent turn produced an acknowledged editor change: turn_id only, at most once per turn. Successful reads and focus/navigation do not prove applied output.</td></tr>
-              <tr><td>mcp:tool_requested</td><td>Connected-editor MCP execution requests: ephemeral request_id and tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other).</td></tr>
-              <tr><td>mcp:tool_executed</td><td>Connected-editor MCP outcomes: request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other), outcome (succeeded, failed, uncertain or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Control-plane success does not prove a mutation applied.</td></tr>
+              <tr><td>mcp:tool_requested</td><td>Connected-editor MCP execution requests: ephemeral request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other) and tool_name, the CozyClay tool that ran (describe_scene, describe_shot, render_prompt, mark_camera_move, describe_camera_move, save_project, set_camera, frame_shot, add_character, place_character, remove_character, focus_character, place_object, import_mesh, sculpt_object, compare_sculpt, group_objects, update_object, remove_object, apply_batch, add_scene, switch_scene, open_project, capture_frame, studio_commands, studio_run or other; never its arguments).</td></tr>
+              <tr><td>mcp:tool_executed</td><td>Connected-editor MCP outcomes: request_id, tool_category (read, camera, scene_write, prompt_authoring, frame_capture, motion_generate, motion_apply, project_io or other), tool_name (describe_scene, describe_shot, render_prompt, mark_camera_move, describe_camera_move, save_project, set_camera, frame_shot, add_character, place_character, remove_character, focus_character, place_object, import_mesh, sculpt_object, compare_sculpt, group_objects, update_object, remove_object, apply_batch, add_scene, switch_scene, open_project, capture_frame, studio_commands, studio_run or other), outcome (succeeded, failed, uncertain or cancelled) and duration_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s). Control-plane success does not prove a mutation applied.</td></tr>
               <tr><td>mcp:result_applied</td><td>A connected editor acknowledged an MCP mutation, paired by request_id. Detached or disconnected MCP sessions remain unobserved.</td></tr>
               <tr><td>export:blocking_frame_succeeded, export:video_succeeded</td><td>Export reliability</td></tr>
               <tr><td>export:attempt_started, export:attempt_succeeded, export:attempt_failed, export:attempt_cancelled</td><td>Export attempts and outcomes, paired by an ephemeral random attempt_id; export_kind (video, depth_video, frame, keyframe_pack, contact_sheet, panel_pack, animatic, animation_project, workflow_send, storyboard, render_pass or otio), format (mp4, png, zip, cclayproject or otio), initiating surface (studio, workflow or embed), is_retry (whether the attempt retries an earlier one), retry_of (the retried attempt's attempt_id, only when is_retry is true) and objects (the scene's object count, bucketed 0, 1-3, 4-10 or gte11). Terminal events include a bucketed duration_bucket; failures and real cancellations include a normalized failure_code (unsupported_codec, encode_failed, render_failed, aborted or unknown), the stage where the export stopped (preparing, encoding, finalizing or handoff) and a progress bucket (0, 1-25, 26-50, 51-75 or 76-99 percent), never raw error messages, filenames, URLs, paths, prompts or scene content. Success means pipeline completion or download handoff, not confirmation that the OS saved a file.</td></tr>
               <tr><td>export:saved</td><td>How each exported file was saved, one event per file: method (workspace, written into the export folder you chose, or download, a browser download) and reason (none; unsupported, the browser has no folder access; no_workspace, no export folder is chosen; permission, folder access was denied; or write_failed, the folder write failed and the file fell back to a download). Never the file name or path.</td></tr>
+              <tr><td>export:menu_opened</td><td>The Export menu opened, once per open: surface (studio or embed), mode (animation or storyboard), webcodecs (whether this browser has the video encoder an MP4 export needs; a yes/no check, not a codec test) and shots (shot count bucket, panels in a storyboard: 0, 1-3, 4-10, gte11). Never shot names or what you exported.</td></tr>
               <tr><td>export:keyframe_pack</td><td>Legacy Workflow pack handoffs, with numeric entries count and source=workflow; not an additional export attempt</td></tr>
               <tr><td>sculpt_run</td><td>One event per finished Sculpt mode run: outcome (done, cancelled or failed), rounds (0 to 10), final_iou (how closely the final sculpt matched the reference image, 0 to 1 rounded to two decimals; omitted when the run was never scored), duration_ms (elapsed run time in milliseconds) and had_target (whether the run reworked an existing sculpt instead of creating one). Numbers only: never the reference image, recipe, part names or sculpt id.</td></tr>
               <tr><td>playground:opened, playground:first_action</td><td>Whether the home-page playground gets used</td></tr>
@@ -131,6 +132,7 @@ cclay telemetry on</code></pre>
               <tr><td>app:gl_lost</td><td>The 3D view's graphics failed, at most once per kind per session: kind (unavailable when WebGL is off at startup, context_lost when the GPU context drops later). Never the GPU renderer string.</td></tr>
               <tr><td>studio:ready</td><td>Once per session: how long the studio took to show its first frame, from page navigation to the first frame after the first render: boot (lt2s, 2-5s, 5-15s or gte15s). Never what was loaded.</td></tr>
               <tr><td>playback:summary</td><td>One per playback run (play until stop, or until the frame rate or speed changes), at most 10 per session: duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m); late_ticks, an estimate of dropped frames, not a measured one: the share of playback timer ticks that had to catch up more than one frame (0, lt5, 5-20, 20-50 or gte50 %); max_catchup (the most frames one tick caught up: 1, 2, 3-5 or gte6); fps (12, 24, 30, 60 or other); speed (0.5, 1, 2 or other); measured_fps (the browser's frame rate during playback, the device:profile frame-rate buckets). Every run also feeds app:friction_summary.late_tick_ratio. Never the scene, the take or the frame range.</td></tr>
+              <tr><td>landing:cta_clicked</td><td>The landing page (cozyclay.org/) sends one $pageview and, when a call to action is pressed, which one: target (app, github, discord, npm, copy_npx, copy_clone, copy_mcp, copy_terminal or agent_install_doc). Never the URL or the copied text. The landing page sends no session, error, device or performance events.</td></tr>
               <tr><td>guide:opened</td><td>The first-60-seconds guide opened, at most once per session: mode (animation or storyboard). Never step text or what you did.</td></tr>
               <tr><td>guide:step</td><td>A guide step marked done, each step at most once per session: mode (animation or storyboard), step (1 to 4) and step_ms (time on that step: lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m).</td></tr>
               <tr><td>guide:dismissed</td><td>The guide closed before its last step, at most once per session: mode (animation or storyboard) and reached (1 to 4, the step it was showing).</td></tr>
@@ -139,8 +141,9 @@ cclay telemetry on</code></pre>
               <tr><td>object:deleted_soon</td><td>You deleted an object you added in this session, at most 10 per session: age (how long after adding it: lt2s, 2-10s, 10-60s or gte60s). Object ids are reused names, so this is an estimate. Never the object's id, name or kind.</td></tr>
               <tr><td>object:delete_undone</td><td>You undid an object deletion within its 7-second undo window, at most 10 per session: age (time from the deletion to the undo: lt2s or 2-10s). Never the object's id, name or kind.</td></tr>
               <tr><td>update:notice_shown</td><td>The update notice appeared in the top bar of an npm studio, once per session: kind (global or npx) and behind (patch, minor or major: how far the running version is behind the newest release). Never a path or a command</td></tr>
-              <tr><td>update:clicked</td><td>A button on the update notice, at most 10 per session: action (update_now, copy_command, later, dismiss or release_notes) and kind (global or npx)</td></tr>
+              <tr><td>update:clicked</td><td>A button on the update notice, at most 10 per session: action (update_now, copy_command, later, dismiss, release_notes or restart) and kind (global or npx)</td></tr>
               <tr><td>update:finished</td><td>A one-click update ended, at most 3 per session: outcome (ok or failed), error_class (none, permission, network, node_version, npm_missing or other) and duration (lt10s, 10-30s, 30-60s, 1-2m, 2-5m or gte5m). Never npm's output, a path or the command line</td></tr>
+              <tr><td>update:restarted</td><td>Restart now ended in the tab that pressed it, once per session: outcome (ok: the updated launcher answered; timeout: it did not within 30 seconds). Never a version string, a path or the command line</td></tr>
               <tr><td>device:profile</td><td>Once per session, whether the studio can run smoothly: gpu_vendor (nvidia, amd, intel, apple, qualcomm, arm, software, other or unknown), gpu_class (discrete, integrated, software or unknown), webgl (webgl2, webgl1 or none), cpu_bucket (1-4, 5-8, 9-16, gte17 or unknown), memory_bucket (lt4, 4-7, gte8 or unknown) and frame_rate_bucket (lt20, 20-40, 40-55, gte55 or unknown) from one three-second sample. The GPU renderer string and exact hardware values never leave the browser.</td></tr>
               <tr><td>survey:use_case</td><td>An optional question shown at most once after a successful export, only while telemetry is on: use_case (animation, film, game, ad_mv, personal, other or skip) and team (team, solo or skip). Closed choices only; no free text.</td></tr>
               <tr><td>hosted:composer_viewed, hosted:login_started, hosted:ticket_created, hosted:result_opened, hosted:opened_in_studio</td><td>Hosted demo funnel</td></tr>

package/tools/dev/pages/seedance-camera-control.html

@@ -87,11 +87,11 @@
           Any 3D tool that renders flat can make the reference. Blender works with a clay material and a
           workbench render. CozyClay, open source and in the browser, exports the flat clip directly with the
           delivery ratio and a camera timeline built in; the reel at the top of this page came out of it.
-          The <a href="/#try">home-page playground</a> runs the studio in the page, and
+          The <a href="/app/">browser studio</a> runs it in a tab, and
           <code>npx cozyclay</code> runs it locally.
         </p>
         <div class="cta">
-          <a class="btn primary" href="/#try">Try it in your browser</a>
+          <a class="btn primary" href="/app/">Try it in your browser</a>
           <a class="btn ghost" href="https://github.com/NomaDamas/CozyClay">View on GitHub</a>
         </div>
       </section>

package/tools/loc-baseline.json

@@ -5,7 +5,7 @@
 	"bin/agent/session-store.mjs": 324,
 	"bin/agent/supervisor.mjs": 283,
 	"bin/agent/video-adapters.mjs": 334,
-	"bin/cozyclay.mjs": 351,
+	"bin/cozyclay.mjs": 348,
 	"bin/live/cli.mjs": 456,
 	"mcp/live-hub.mjs": 529,
 	"mcp/tool-handlers.mjs": 1730,
@@ -15,11 +15,11 @@
 	"mcp/verify-live-p0.mjs": 264,
 	"mcp/verify-live.mjs": 416,
 	"src/analytics.js": 948,
-	"src/App.jsx": 4434,
-	"src/asset-pane.jsx": 642,
+	"src/App.jsx": 4418,
+	"src/asset-pane.jsx": 614,
 	"src/camera-follow.js": 505,
 	"src/camera-move.js": 289,
-	"src/command-bus.js": 355,
+	"src/command-bus.js": 341,
 	"src/controls.jsx": 330,
 	"src/domains/cast.js": 717,
 	"src/domains/motion.js": 806,
@@ -33,21 +33,21 @@
 	"src/matte.js": 472,
 	"src/motion/collision-blockers.js": 273,
 	"src/motion/fix-collisions.js": 748,
-	"src/motion/ik.js": 1135,
+	"src/motion/ik.js": 1128,
 	"src/motion/range-pin.js": 277,
 	"src/motion/timeline.jsx": 2042,
 	"src/object-gizmo.jsx": 740,
 	"src/object-path.js": 410,
 	"src/panels/ObjectTransformPanel.jsx": 545,
-	"src/panels/SculptPanel.jsx": 370,
+	"src/panels/SculptPanel.jsx": 369,
 	"src/planview.jsx": 887,
 	"src/poses.js": 321,
-	"src/posestudio.jsx": 1240,
+	"src/posestudio.jsx": 1226,
 	"src/project-browser.jsx": 371,
 	"src/project.js": 603,
 	"src/props.jsx": 414,
 	"src/range-pin-panel.jsx": 305,
-	"src/scene-assets.js": 400,
+	"src/scene-assets.js": 399,
 	"src/scene-mesh.js": 350,
 	"src/scene-objects.js": 1134,
 	"src/scenes.js": 385,
@@ -56,7 +56,7 @@
 	"src/sculpt-run.js": 309,
 	"src/shell/BoardSlot.jsx": 316,
 	"src/shell/BottomDock.jsx": 416,
-	"src/shell/DetailsSlot.jsx": 334,
+	"src/shell/DetailsSlot.jsx": 333,
 	"src/shell/MenuBar.jsx": 632,
 	"src/shell/ViewportToolbar.jsx": 567,
 	"src/shot-authoring.js": 345,
@@ -70,5 +70,5 @@
 	"src/workflow/AgentPanel.jsx": 807,
 	"src/workflow/WorkflowBuilder.jsx": 592,
 	"tools/qa/css-rule-usage.mjs": 251,
-	"tools/run-tests.mjs": 441
+	"tools/run-tests.mjs": 407
 }

package/tools/run-tests.mjs

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { availableParallelism, tmpdir } from "node:os";
 import { join, relative } from "node:path";
+import { assignShards, parseShard, readDurations, readSelection, reportDurations, slowestFirst } from "./test-shards.mjs";
 
 // Whatever a suite drives through the agent sidecar lands in a scratch
 // session dir for the whole run, never in the author's ~/.config (#375).
@@ -13,16 +14,16 @@ if (!process.env.COZYCLAY_AGENT_SESSIONS_DIR) {
 }
 
 const NODE_FILES = [
-	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-playback-frame-store.mjs", "test/verify-playback-render-isolation.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-life.mjs", "test/motion3/verify-motion3-headlead.mjs", "test/motion3/verify-motion3-gait.mjs", "test/motion3/verify-motion3-overlap.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-float-fix.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-person-fix.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-shapes.mjs", "test/motion3/verify-motion3-grasp-fields.mjs", "test/motion3/verify-motion3-finger-contact.mjs", "test/motion3/verify-motion3-finger-pose.mjs", "test/motion3/verify-motion3-grasp-qa.mjs", "test/motion3/verify-motion3-load.mjs", "test/motion3/verify-motion3-throw.mjs", "test/motion3/verify-motion3-catch.mjs", "test/motion3/verify-motion3-spring.mjs", "test/motion3/verify-motion3-grasp-hints.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-patch-keys.mjs", "test/motion3/verify-motion3-stuck.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/motion3/verify-motion3-arm.mjs", "test/motion3/verify-motion3-balance.mjs", "test/motion3/verify-physics-overlay.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
+	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-playback-frame-store.mjs", "test/verify-playback-render-isolation.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-life.mjs", "test/motion3/verify-motion3-headlead.mjs", "test/motion3/verify-motion3-gait.mjs", "test/motion3/verify-motion3-overlap.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-float-fix.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-person-fix.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-shapes.mjs", "test/motion3/verify-motion3-grasp-fields.mjs", "test/motion3/verify-motion3-finger-contact.mjs", "test/motion3/verify-motion3-finger-pose.mjs", "test/motion3/verify-motion3-grasp-qa.mjs", "test/motion3/verify-motion3-load.mjs", "test/motion3/verify-motion3-load-faces.mjs", "test/motion3/verify-motion3-throw.mjs", "test/motion3/verify-motion3-catch.mjs", "test/motion3/verify-motion3-spring.mjs", "test/motion3/verify-motion3-grasp-hints.mjs", "test/motion3/verify-motion3-ball-pickup-repair.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-patch-keys.mjs", "test/motion3/verify-motion3-stuck.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/motion3/verify-motion3-arm.mjs", "test/motion3/verify-motion3-balance.mjs", "test/motion3/verify-physics-overlay.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
 	"test/verify-proxy-figure-bounds.mjs",
-	"test/verify-character-capabilities.mjs",
-	"test/verify-root-path.mjs",
+	"test/verify-character-capabilities.mjs", "test/verify-test-shards.mjs", "test/verify-select-tests.mjs",
+	"test/verify-root-path.mjs", "test/verify-tutorial-recorder.mjs",
 	"test/verify-studio-elements.mjs",
 	"test/bus/verify-view-mode-pose.mjs",
 	"test/verify-studio-actions.mjs",
 	"test/ardy/verify-collision-blockers.mjs",
 	"test/verify-pose-fade.mjs",
-	"test/verify-pose-gizmo.mjs",
+	"test/verify-pose-gizmo.mjs", "test/verify-fingertip-pick.mjs",
 	"test/ardy/verify-key-runs.mjs",
 	"test/ardy/verify-playback-clock.mjs",
 	"test/ardy/verify-timeline-coordinates.mjs",
@@ -64,7 +65,7 @@ const NODE_FILES = [
 	"test/verify-agent-sse-golden.mjs",
 	"test/verify-agent-context-budget.mjs", "test/verify-agent-context-trim.mjs",
 	"test/verify-agent-supervisor.mjs", "test/verify-studio-tasks.mjs", "test/verify-task-board.mjs",
-	"test/verify-studio-agent-protocol.mjs",
+	"test/verify-studio-agent-protocol.mjs", "test/verify-studio-prompt-cast-style.mjs",
 	"test/verify-studio-agent-sampled-framing.mjs",
 	"test/verify-studio-agent-tokens.mjs",
 	"test/verify-agent-execution.mjs",
@@ -131,7 +132,7 @@ const NODE_FILES = [
 	"test/verify-project.mjs",
 	"test/verify-workflow-send.mjs",
 	"test/verify-animation-export.mjs",
-	"test/verify-project-previs-mode.mjs",
+	"test/verify-project-previs-mode.mjs", "test/verify-project-cast-style.mjs",
 	"test/verify-pwa.mjs",
 	"test/verify-package-signature.mjs",
 	"test/verify-resilience.mjs",
@@ -211,10 +212,10 @@ const NODE_FILES = [
 const BROWSER_FILES = [
 	"test/qa-proxy-entry-browser.mjs",
 	"test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs", "test/qa-ik-contact-browser.mjs",
-	"test/qa-storyboard-board-browser.mjs",
+	"test/qa-storyboard-board-browser.mjs", "test/qa-sculpt-shelf-browser.mjs",
 	"test/qa-storyboard-export-browser.mjs", "test/qa-playback-guide-browser.mjs",
-	"test/qa-proxy-figure-browser.mjs", "test/qa-click-friction-browser.mjs", "test/qa-update-notice-browser.mjs",
-	"test/qa-rail-lean-browser.mjs",
+	"test/qa-proxy-figure-browser.mjs", "test/qa-click-friction-browser.mjs", "test/qa-update-notice-browser.mjs", "test/qa-export-menu-browser.mjs",
+	"test/qa-rail-lean-browser.mjs", "test/qa-sculpt-parts-browser.mjs",
 	"test/qa-export-recovery-browser.mjs", "test/qa-export-workspace-browser.mjs",
 	"test/verify-camera-mode-browser.mjs",
 	"test/verify-camera-rail-browser.mjs",
@@ -257,9 +258,9 @@ const BROWSER_FILES = [
 const EXTRA_INVENTORY = ["test/ik/translation-step.mjs", "test/qa-scenes-v5-migration-browser.mjs", "test/qa-agent-scenarios-browser.mjs", "test/qa-execution-outcomes-browser.mjs", "test/qa-export-recovery-browser.mjs", "test/qa-agent-view-toggle-browser.mjs", "test/qa-camera-pointer-lock-browser.mjs", "test/qa-first-edit-browser.mjs", "test/qa-ia-tail-browser.mjs", "test/qa-keyframe-pack-browser.mjs", "test/qa-preview-browser.mjs", "test/qa-reference-slots-browser.mjs", "test/qa-scene-playback-browser.mjs", "test/qa-scene-switcher-browser.mjs", "test/qa-send-to-ai-browser.mjs", "test/qa-view-menu-browser.mjs", "test/qa-live-reconnect-browser.mjs", "test/qa-clipboard-paste-browser.mjs", "test/qa-rail-lean-browser.mjs", "test/qa-rail-reach-browser.mjs", "test/qa-rail-ring-browser.mjs", "test/qa-speed-graph-browser.mjs", "test/qa-export-workspace-browser.mjs"];
 
 EXTRA_INVENTORY.push("test/qa-proxy-figure-browser.mjs", "test/qa-click-friction-browser.mjs", "test/qa-update-notice-browser.mjs");
-EXTRA_INVENTORY.push("test/qa-proxy-entry-browser.mjs");
+EXTRA_INVENTORY.push("test/qa-proxy-entry-browser.mjs", "test/qa-export-menu-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs", "test/qa-ik-contact-browser.mjs");
-EXTRA_INVENTORY.push("test/qa-storyboard-board-browser.mjs");
+EXTRA_INVENTORY.push("test/qa-storyboard-board-browser.mjs", "test/qa-sculpt-parts-browser.mjs", "test/qa-sculpt-shelf-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-storyboard-export-browser.mjs", "test/qa-playback-guide-browser.mjs");
 
 function verificationFiles(directory) {
@@ -275,56 +276,38 @@ function verificationFiles(directory) {
 // Every suite reserves its own ports and writes under a temp dir, so files
 // are independent of each other; running them serially cost CI five minutes
 // (#413). `--jobs 1` restores the old interleaved live output for debugging.
-// `--shard INDEX/TOTAL` selects a deterministic round-robin slice for CI
-// runners. Shards are disjoint over the sorted inventory and together cover
-// the same runnable set as an unsharded invocation.
+// `--shard INDEX/TOTAL` selects a deterministic slice for CI runners, balanced
+// by the recorded seconds in tools/test-durations.json (tools/test-shards.mjs).
+// Shards are disjoint and together cover the same runnable set as an unsharded
+// invocation. `--durations-out PATH` writes each file's wall-clock seconds.
+// `--only-from SELECTION.json` (tools/select-tests.mjs) narrows the runnable
+// set before sharding; a shard left with no files passes.
 function parseArguments(arguments_) {
-	let listOnly = false;
-	let scope = "all";
-	let jobs = Number(process.env.COZYCLAY_TEST_JOBS) || availableParallelism();
-	let shard = null;
+	const options = { listOnly: false, scope: "all", jobs: Number(process.env.COZYCLAY_TEST_JOBS) || availableParallelism(), shard: null, durationsOut: null, onlyFrom: null };
+	const valued = { "--scope": "scope", "--jobs": "jobs", "--shard": "shard", "--durations-out": "durationsOut", "--only-from": "onlyFrom" };
 	for (let index = 0; index < arguments_.length; index += 1) {
 		const argument = arguments_[index];
-		if (argument === "--list") {
-			listOnly = true;
-			continue;
-		}
-		if (argument === "--scope") {
-			scope = arguments_[index + 1] ?? "";
-			index += 1;
-			continue;
-		}
-		if (argument === "--jobs") {
-			jobs = Number(arguments_[index + 1]);
-			index += 1;
-			continue;
-		}
-		if (argument === "--shard") {
-			const value = arguments_[index + 1] ?? "";
-			const match = /^(\d+)\/(\d+)$/.exec(value);
-			if (!match) throw new Error(`--shard must be INDEX/TOTAL with 1 <= INDEX <= TOTAL, got ${value}`);
-			const current = Number(match[1]);
-			const total = Number(match[2]);
-			if (!Number.isInteger(current) || !Number.isInteger(total) || current < 1 || total < 1 || current > total) {
-				throw new Error(`--shard must be INDEX/TOTAL with 1 <= INDEX <= TOTAL, got ${value}`);
-			}
-			shard = { current, total };
-			index += 1;
-			continue;
-		}
-		throw new Error(`unknown argument: ${argument}`);
+		if (argument === "--list") options.listOnly = true;
+		else if (Object.hasOwn(valued, argument)) options[valued[argument]] = arguments_[(index += 1)] ?? "";
+		else throw new Error(`unknown argument: ${argument}`);
 	}
-	if (scope !== "all" && scope !== "ardy") throw new Error(`unknown test scope: ${scope}`);
-	if (!Number.isInteger(jobs) || jobs < 1) throw new Error(`--jobs must be a positive integer, got ${jobs}`);
-	return { listOnly, scope, jobs, shard };
+	options.jobs = Number(options.jobs);
+	if (options.shard !== null) options.shard = parseShard(options.shard);
+	if (options.scope !== "all" && options.scope !== "ardy") throw new Error(`unknown test scope: ${options.scope}`);
+	if (!Number.isInteger(options.jobs) || options.jobs < 1) throw new Error(`--jobs must be a positive integer, got ${options.jobs}`);
+	if (options.durationsOut === "" || options.onlyFrom === "") throw new Error("--durations-out and --only-from need a file path");
+	return options;
 }
 
 // One file per child. With more than one job the output is buffered per file
 // and replayed as a block when the file finishes, so PASS/FAIL lines of
-// different suites never interleave.
+// different suites never interleave. Each file's wall-clock seconds land in
+// `timings` for --durations-out and the CI step summary.
+const timings = new Map();
 function run(file, { buffered }) {
 	return new Promise((resolve, reject) => {
 		const chunks = [];
+		const started = performance.now();
 		const child = spawn(process.execPath, [file], { stdio: buffered ? ["ignore", "pipe", "pipe"] : "inherit" });
 		if (buffered) {
 			child.stdout.on("data", (chunk) => chunks.push(chunk));
@@ -332,6 +315,7 @@ function run(file, { buffered }) {
 		}
 		child.once("error", reject);
 		child.once("exit", (code, signal) => {
+			timings.set(file, (performance.now() - started) / 1000);
 			if (buffered) process.stdout.write(`\nRUNNING ${file}\n${Buffer.concat(chunks)}`);
 			if (code === 0) resolve();
 			else reject(new Error(`${file} failed${signal ? ` with ${signal}` : ` with exit code ${code}`}`));
@@ -352,17 +336,8 @@ const SERIAL_ONLY = new Set([
 	"mcp/verify-live-routing.mjs",
 ]);
 
-// Longest files first so the tail of the run is not one slow suite on its own.
-const SLOW_FIRST = [
-	"test/verify-studio-agent-motion.mjs",
-	"test/verify-studio-agent-binding.mjs",
-	"test/verify-part-colours.mjs",
-	"test/verify-agent-runner-errors.mjs",
-];
-
 async function runAll(files, jobs) {
-	const parallel = files.filter((file) => !SERIAL_ONLY.has(file));
-	const queue = [...SLOW_FIRST.filter((file) => parallel.includes(file)), ...parallel.filter((file) => !SLOW_FIRST.includes(file))];
+	const queue = slowestFirst(files.filter((file) => !SERIAL_ONLY.has(file)), durations);
 	let failure = null;
 	const worker = async () => {
 		while (queue.length > 0 && !failure) {
@@ -440,7 +415,8 @@ if (!mcpDepsInstalled) {
 	}
 }
 
-const { listOnly, scope, jobs, shard } = parseArguments(process.argv.slice(2));
+const { listOnly, scope, jobs, shard, durationsOut, onlyFrom } = parseArguments(process.argv.slice(2));
+const durations = readDurations();
 const inventory = [...verificationFiles("test"), ...verificationFiles("mcp"), ...EXTRA_INVENTORY].sort();
 for (const file of inventory) {
 	if (/^test\/bus\/verify-.*\.mjs$/.test(file)) categories.set(file, { kind: "node", reason: "command bus contract verification" });
@@ -455,24 +431,24 @@ if (unclassified.length > 0 || stale.length > 0) {
 }
 
 const scoped = inventory.filter((file) => scope === "all" || file.startsWith("test/ardy/") || file.startsWith("test/ik/"));
-const runnable = scoped.filter((file) => categories.get(file).kind === "node");
-const selected = shard ? runnable.filter((_, index) => index % shard.total === shard.current - 1) : runnable;
+const only = readSelection(onlyFrom);
+const runnable = scoped.filter((file) => categories.get(file).kind === "node" && (!only || only.has(file)));
+const { files: selected, predicted } = assignShards(runnable, durations, shard?.total ?? 1)[(shard?.current ?? 1) - 1];
 const selectedSet = new Set(selected);
 console.log(
 	`TEST MANIFEST scope=${scope} runnable=${runnable.length} selected=${selected.length} total=${scoped.length} jobs=${jobs}${
 		shard ? ` shard=${shard.current}/${shard.total}` : ""
-	}`,
+	} predicted=${predicted.toFixed(1)}s`,
 );
 for (const file of scoped) {
 	const { kind, reason } = categories.get(file);
-	if (kind === "node" && shard && !selectedSet.has(file)) {
-		console.log(`SHARD node ${file} - assigned to another shard`);
-		continue;
-	}
-	console.log(`${kind === "node" ? "RUN" : "EXCLUDE"} ${kind} ${file} - ${reason}`);
+	if (kind === "node" && only && !only.has(file)) console.log(`SKIP node ${file} - not selected by ${onlyFrom}`);
+	else if (kind === "node" && shard && !selectedSet.has(file)) console.log(`SHARD node ${file} - assigned to another shard`);
+	else console.log(`${kind === "node" ? "RUN" : "EXCLUDE"} ${kind} ${file} - ${reason}`);
 }
 
 if (!listOnly) {
+	process.on("exit", () => reportDurations(timings, { out: durationsOut, selected: selected.length, predicted }));
 	if (jobs === 1) {
 		for (const file of selected) {
 			console.log(`\nRUNNING ${file}`);

package/tools/select-tests.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Change-based test selection for pull requests (#632).
+//   git diff --name-only --no-renames origin/main...HEAD | node tools/select-tests.mjs --out selection.json
+// reads changed paths (stdin, or --changed FILE) and writes the Node tests a
+// shard must run: `node tools/run-tests.mjs --only-from selection.json`.
+// Anything the selector cannot vouch for becomes mode "full" with a reason.
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { buildGraph, reverseIndex, sweepVerifyFiles } from "./test-graph.mjs";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+// Changes that can alter any test's outcome, or the selection itself.
+const FULL_TRIGGERS = [
+	/^package(-lock)?\.json$/, /^mcp\/package(-lock)?\.json$/, /^(vite|eslint)\.config\.js$/, /^knip\.json$/,
+	/^tools\/(run-tests|test-shards|select-tests|test-graph|qa-browser)\.mjs$/, /^tools\/[^/]+-baseline\.json$/,
+	/^\.github\/workflows\/[^/]+\.ya?ml$/,
+	/^test\/bus\/[^/]+-fixture\.mjs$/, /^test\/fixtures\//, /^test\/motion3\/fixtures\//, /^test\/camera-browser-harness\.mjs$/,
+];
+// The paths ci.yml's `changes` job already treats as not needing tests.
+const IGNORED = (file) => file.startsWith(".metrics/") || /^docs\/.*\.md$/.test(file) || /^[^/]+\.md$/.test(file);
+// Browser suites run in their own CI lanes, never on the Node shards.
+const BROWSER_ONLY = (file) => file.startsWith("test/") && /(?:^|\/)qa-[^/]*\.mjs$|-browser\.mjs$/.test(file);
+
+// Cheap boot checks that run on every selected PR (at most 10).
+export const ALWAYS_RUN = [
+	"test/bus/verify-manifest.mjs",
+	"test/verify-mcp-invariants.mjs",
+	"test/verify-package-agent-imports.mjs",
+	"test/verify-error-boundary.mjs",
+	"test/verify-tool-handlers.mjs",
+	"test/verify-pwa.mjs",
+	"mcp/verify.mjs",
+];
+
+// `node tools/run-tests.mjs --list`, as [{ file, kind }]. mcp-deps entries are
+// runnable on a shard (it installs mcp/node_modules) even if not here.
+export function readManifest(root = ROOT) {
+	const result = spawnSync(process.execPath, ["tools/run-tests.mjs", "--list"], { cwd: root, encoding: "utf8" });
+	if (result.status !== 0) throw new Error(`run-tests --list failed: ${result.stderr.trim().split("\n")[0]}`);
+	return [...result.stdout.matchAll(/^(?:RUN|EXCLUDE) (\S+) (\S+) - /gm)].map(([, kind, file]) => ({ kind, file }));
+}
+
+// Test directories a path falls back to when no test reaches it, deepest
+// first: src/motion3/a/b.js → test/motion3/a/, test/motion3/. A top-level
+// directory never maps (it would be the whole suite).
+function prefixesFor(file) {
+	const parts = file.split("/").slice(0, -1);
+	const prefixes = [];
+	for (let depth = parts.length; depth >= 2; depth -= 1) {
+		const directory = parts.slice(0, depth);
+		prefixes.push(`${directory.join("/")}/`);
+		if (["src", "bin", "tools"].includes(directory[0])) prefixes.push(`test/${directory.slice(1).join("/")}/`);
+	}
+	return prefixes;
+}
+
+const full = (reason, base) => ({ ...base, mode: "full", reason, files: base.runnable, selected: base.total });
+
+export function selectTests(changed, { root = ROOT, manifest = readManifest(root), always = ALWAYS_RUN } = {}) {
+	const runnable = manifest.filter(({ kind }) => kind === "node" || kind === "mcp-deps").map(({ file }) => file).sort();
+	const runnableSet = new Set(runnable);
+	const inventory = new Set(manifest.map(({ file }) => file));
+	const paths = [...new Set(changed.map((file) => file.trim()).filter(Boolean))];
+	const base = { changed: paths.length, total: runnable.length, alwaysRun: 0, runnable };
+	const trigger = paths.find((file) => FULL_TRIGGERS.some((pattern) => pattern.test(file)));
+	if (trigger) return full(`full-run trigger: ${trigger}`, base);
+	const unknown = [...sweepVerifyFiles(root, "test"), ...sweepVerifyFiles(root, "mcp")].filter((file) => !inventory.has(file));
+	if (unknown.length > 0) return full(`inventory mismatch: ${unknown.slice(0, 3).join(", ")}`, base);
+
+	const graph = buildGraph(root, runnable);
+	const readers = reverseIndex(graph);
+	const alwaysSet = new Set([...always.filter((file) => runnableSet.has(file)), ...runnable.filter((file) => graph.get(file).unresolved)]);
+	const selected = new Set(alwaysSet);
+	for (const file of paths) {
+		if (IGNORED(file) || (inventory.has(file) && !runnableSet.has(file))) continue;
+		if (runnableSet.has(file)) selected.add(file);
+		const tests = readers(file);
+		if (tests.size === 0 && BROWSER_ONLY(file)) continue;
+		for (const prefix of tests.size > 0 ? [] : prefixesFor(file)) {
+			for (const test of runnable) if (test.startsWith(prefix)) tests.add(test);
+			if (tests.size > 0) break;
+		}
+		if (tests.size === 0 && !runnableSet.has(file)) return full(`no test reaches ${file}`, { ...base, alwaysRun: alwaysSet.size });
+		for (const test of tests) selected.add(test);
+	}
+	const result = { ...base, alwaysRun: alwaysSet.size, mode: "selected", reason: "", files: [...selected].sort(), selected: selected.size };
+	if (selected.size * 2 >= runnable.length) return full(`selection ${selected.size}/${runnable.length} is 50% or more`, result);
+	return result;
+}
+
+// Any exception is a full run: a selector bug must never skip a test.
+export function safeSelect(changed, options) {
+	try {
+		return selectTests(changed, options);
+	} catch (error) {
+		return { mode: "full", reason: `selector error: ${error.message}`, changed: changed.length, files: [], selected: 0, total: 0, alwaysRun: 0 };
+	}
+}
+
+export function summaryTable({ changed, mode, reason, selected, total, alwaysRun }) {
+	return [
+		"### Test selection (#632)", "",
+		"| Changed files | Mode | Fallback reason | Selected / total | Always run |", "|---|---|---|---|---|",
+		`| ${changed} | ${mode} | ${reason.replaceAll("|", "\\|") || "-"} | ${selected} / ${total} | ${alwaysRun} |`, "",
+	].join("\n");
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const flag = (name) => process.argv[process.argv.indexOf(name) + 1];
+	const input = process.argv.includes("--changed") ? readFileSync(flag("--changed"), "utf8") : readFileSync(0, "utf8");
+	const { runnable, ...selection } = safeSelect(input.split("\n"));
+	const json = `${JSON.stringify(selection, null, "\t")}\n`;
+	if (process.argv.includes("--out")) writeFileSync(flag("--out"), json);
+	else process.stdout.write(json);
+	if (process.env.GITHUB_STEP_SUMMARY && existsSync(process.env.GITHUB_STEP_SUMMARY)) appendFileSync(process.env.GITHUB_STEP_SUMMARY, summaryTable(selection));
+	console.error(`select-tests: ${selection.mode} ${selection.selected}/${selection.total}${selection.reason ? ` (${selection.reason})` : ""}`);
+}