@go-labs-sg/gosh 1.5.0 → 1.6.0

package/README.md

@@ -372,6 +372,49 @@ groups to read back release values and editability, and use
 for the five most recent actor/before/after changes; the existing event activity
 timeline provides the full audit history.
 
+### Staggered team starts within a group
+
+Teams sharing a route can start at different times. A team's own `releaseAt`
+replaces the group's time (earlier or later); with none, the team uses the
+group's time, so existing events are unchanged. A held group still holds every
+team, and a team hold holds one team inside a released group. The server
+enforces each team's effective time on every gameplay call.
+
+Preview a stagger first. It writes nothing and lists each team's before/after
+time plus any blockers the apply would refuse with:
+
+```bash
+gosh routing-group stagger-preview \
+  --input '{"eventId":"event-id","groupId":"group-a","mode":"STAGGER","firstReleaseAt":"2030-01-01T13:40:00+08:00","intervalMinutes":5,"teamIds":["team-1","team-2","team-3"]}'
+gosh routing-group stagger \
+  --input '{"eventId":"event-id","groupId":"group-a","mode":"STAGGER","firstReleaseAt":"2030-01-01T13:40:00+08:00","intervalMinutes":5,"teamIds":["team-1","team-2","team-3"]}' \
+  --target group-a \
+  --allow-state-change
+```
+
+`teamIds` order is start order: `team-1` 13:40, `team-2` 13:45, `team-3` 13:50.
+Teams left out keep their current time. Use `"mode":"SHIFT","shiftMinutes":10`
+to delay every unstarted scheduled team by 10 minutes (negative moves earlier,
+never into the past), or `"mode":"CLEAR"` to drop team times so teams use the
+group time again. Apply runs in one transaction, so either every team changes
+or none do. Started teams are never rescheduled.
+
+One team at a time, including while LIVE:
+
+```bash
+gosh team release \
+  --input '{"eventId":"event-id","teamId":"team-2","action":"HOLD"}' \
+  --target team-2 \
+  --allow-state-change
+gosh team release-history --input '{"eventId":"event-id","teamId":"team-2"}'
+```
+
+Actions are SCHEDULE (future `releaseAt` with offset), CLEAR (use the group
+time), HOLD, RELEASE_HOLD (keep the team time) and RELEASE_NOW (start this team
+now; refused while the group is held). After a team starts, only HOLD and
+RELEASE_HOLD are accepted. Every change is audited with actor and before/after
+values.
+
 The server evaluates deadlines without cron. Release never starts a timer or
 bypasses LIVE status, availability, check-in or captain permissions. Any team in
 a group beginning play locks that group's schedule; emergency HOLD/resume stays

package/command-manifest.json

@@ -1201,6 +1201,44 @@
 		"summary": "Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, RELEASE_SCHEDULED_HOLD (keep schedule), or RELEASE_NOW for a routing group. After a group starts, only HOLD and RELEASE_SCHEDULED_HOLD are accepted. Requires launchEvent permission.",
 		"targetKeys": ["groupId", "eventId"]
 	},
+	{
+		"effects": [],
+		"input": "json",
+		"operation": "query",
+		"path": ["routing-group", "stagger-preview"],
+		"procedure": "team.previewRoutingGroupStagger",
+		"requiresAuth": true,
+		"summary": "Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with."
+	},
+	{
+		"effects": ["state-change"],
+		"input": "json",
+		"operation": "mutation",
+		"path": ["routing-group", "stagger"],
+		"procedure": "team.applyRoutingGroupStagger",
+		"requiresAuth": true,
+		"summary": "Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.",
+		"targetKeys": ["groupId", "eventId"]
+	},
+	{
+		"effects": ["state-change"],
+		"input": "json",
+		"operation": "mutation",
+		"path": ["team", "release"],
+		"procedure": "team.updateTeamRelease",
+		"requiresAuth": true,
+		"summary": "Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.",
+		"targetKeys": ["teamId", "eventId"]
+	},
+	{
+		"effects": [],
+		"input": "json",
+		"operation": "query",
+		"path": ["team", "release-history"],
+		"procedure": "team.listTeamReleaseHistory",
+		"requiresAuth": true,
+		"summary": "Show a team's five most recent start-time changes with actor, action and before/after UTC values."
+	},
 	{
 		"effects": ["state-change"],
 		"input": "json",

package/command-reference.md

@@ -474,6 +474,38 @@ Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, REL
 - Input: `--input '<json>'` required
 - Effects: state-change
 
+## `gosh routing-group stagger-preview`
+
+Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: read-only
+
+## `gosh routing-group stagger`
+
+Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: state-change
+
+## `gosh team release`
+
+Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: state-change
+
+## `gosh team release-history`
+
+Show a team's five most recent start-time changes with actor, action and before/after UTC values.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: read-only
+
 ## `gosh routing-group create`
 
 Create a routing group within an event before play starts.

package/dist/index.js

@@ -7504,6 +7504,22 @@ var typedOperations = {
     kind: "mutation",
     invoke: (client, input) => client.team.updateRoutingGroupRelease.mutate(input)
   },
+  "team.previewRoutingGroupStagger": {
+    kind: "query",
+    invoke: (client, input) => client.team.previewRoutingGroupStagger.query(input)
+  },
+  "team.applyRoutingGroupStagger": {
+    kind: "mutation",
+    invoke: (client, input) => client.team.applyRoutingGroupStagger.mutate(input)
+  },
+  "team.updateTeamRelease": {
+    kind: "mutation",
+    invoke: (client, input) => client.team.updateTeamRelease.mutate(input)
+  },
+  "team.listTeamReleaseHistory": {
+    kind: "query",
+    invoke: (client, input) => client.team.listTeamReleaseHistory.query(input)
+  },
   "team.createRoutingGroup": {
     kind: "mutation",
     invoke: (client, input) => client.team.createRoutingGroup.mutate(input)
@@ -7989,6 +8005,8 @@ var defaultMutationTargetKeys = [
 ];
 var mutationTargetKeys = {
   "team.updateRoutingGroupRelease": ["groupId", "eventId"],
+  "team.updateTeamRelease": ["teamId", "eventId"],
+  "team.applyRoutingGroupStagger": ["groupId", "eventId"],
   "team.setGameplaySettings": ["eventId"],
   "event.updateSurveySettings": ["eventId"],
   "team.createRoutingGroup": ["eventId"],
@@ -8117,6 +8135,10 @@ var commands = [
   query(["routing-group", "list"], "team.listRoutingGroups", "List an event's routing groups, ordered stations, and assigned teams."),
   query(["routing-group", "release-history"], "team.listRoutingGroupReleaseHistory", "Show a routing group's five most recent release changes with actor, action and before/after UTC values."),
   mutation(["routing-group", "release"], "team.updateRoutingGroupRelease", "Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, RELEASE_SCHEDULED_HOLD (keep schedule), or RELEASE_NOW for a routing group. After a group starts, only HOLD and RELEASE_SCHEDULED_HOLD are accepted. Requires launchEvent permission.", ["state-change"]),
+  query(["routing-group", "stagger-preview"], "team.previewRoutingGroupStagger", "Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with."),
+  mutation(["routing-group", "stagger"], "team.applyRoutingGroupStagger", "Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.", ["state-change"]),
+  mutation(["team", "release"], "team.updateTeamRelease", "Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.", ["state-change"]),
+  query(["team", "release-history"], "team.listTeamReleaseHistory", "Show a team's five most recent start-time changes with actor, action and before/after UTC values."),
   mutation(["routing-group", "create"], "team.createRoutingGroup", "Create a routing group within an event before play starts.", ["state-change"]),
   mutation(["routing-group", "rename"], "team.renameRoutingGroup", "Rename an event's routing group before play starts.", ["state-change"]),
   mutation(["routing-group", "delete"], "team.deleteRoutingGroup", "Delete an unassigned routing group before play starts.", ["state-change", "delete"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/gosh",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "GOSH CLI for organizers and AI agents — manage organizations, events, teams, stations, missions, templates, and live operations through the GOSH API.",
   "type": "module",
   "main": "./dist/index.js",