Fix todos update silently clearing completion subscribers

.surface

@@ -13091,6 +13091,7 @@ FLAG basecamp todos create --markdown type=bool
 FLAG basecamp todos create --md type=bool
 FLAG basecamp todos create --no-hints type=bool
 FLAG basecamp todos create --no-stats type=bool
+FLAG basecamp todos create --notify-on-completion type=string
 FLAG basecamp todos create --profile type=string
 FLAG basecamp todos create --project type=string
 FLAG basecamp todos create --quiet type=bool
@@ -13359,9 +13360,11 @@ FLAG basecamp todos update --md type=bool
 FLAG basecamp todos update --no-description type=bool
 FLAG basecamp todos update --no-due type=bool
 FLAG basecamp todos update --no-hints type=bool
+FLAG basecamp todos update --no-notify-on-completion type=bool
 FLAG basecamp todos update --no-starts-on type=bool
 FLAG basecamp todos update --no-stats type=bool
 FLAG basecamp todos update --notify type=bool
+FLAG basecamp todos update --notify-on-completion type=string
 FLAG basecamp todos update --profile type=string
 FLAG basecamp todos update --project type=string
 FLAG basecamp todos update --quiet type=bool

e2e/smoke/smoke_todos_write.bats

@@ -138,6 +138,55 @@ setup_file() {
  run_smoke basecamp todos trash "$todo_id" -p "$QA_PROJECT" --json
 }
 
+@test "todos update preserves completion subscribers" {
+ # Own person ID for use as a completion subscriber
+ run_smoke basecamp api get /my/profile.json --json
+ assert_success
+ local person_id
+ person_id=$(echo "$output" | jq -r '.data.id')
+ [[ -n "$person_id" && "$person_id" != "null" ]] || mark_unverifiable "Cannot resolve own person ID"
+
+ # Create with a due date and a completion subscriber
+ run_smoke basecamp todos create "Subscriber preservation test $(date +%s)" \
+ --list "$QA_TODOLIST" -p "$QA_PROJECT" \
+ --due "2026-08-15" \
+ --notify-on-completion "$person_id" --json
+ assert_success
+ local todo_id
+ todo_id=$(echo "$output" | jq -r '.data.id')
+
+ # Title-only update (typed merge branch) must preserve the subscriber
+ run_smoke basecamp todos update "$todo_id" --title "Renamed, subscriber kept" --json
+ assert_success
+
+ run_smoke basecamp api get "/todos/$todo_id.json" --json
+ assert_success
+ local subs
+ subs=$(echo "$output" | jq -r '[.data.completion_subscribers[].id] | join(",")')
+ [[ "$subs" == "$person_id" ]] || { echo "subscriber lost after title update: [$subs]"; return 1; }
+
+ # --no-due (raw clear branch) must also preserve the subscriber
+ run_smoke basecamp todos update "$todo_id" --no-due --json
+ assert_success
+
+ run_smoke basecamp api get "/todos/$todo_id.json" --json
+ assert_success
+ subs=$(echo "$output" | jq -r '[.data.completion_subscribers[].id] | join(",")')
+ [[ "$subs" == "$person_id" ]] || { echo "subscriber lost after --no-due: [$subs]"; return 1; }
+
+ # --no-notify-on-completion clears the subscribers
+ run_smoke basecamp todos update "$todo_id" --no-notify-on-completion --json
+ assert_success
+
+ run_smoke basecamp api get "/todos/$todo_id.json" --json
+ assert_success
+ subs=$(echo "$output" | jq -r '.data.completion_subscribers | length')
+ [[ "$subs" == "0" ]] || { echo "subscribers not cleared: $subs remain"; return 1; }
+
+ # Clean up
+ run_smoke basecamp todos trash "$todo_id" -p "$QA_PROJECT" --json
+}
+
 @test "todos trash trashes a todo" {
  local id_file="$BATS_FILE_TMPDIR/direct_todo_id"
  [[ -f "$id_file" ]] || mark_unverifiable "No direct todo created in prior test"

internal/commands/cards.go

@@ -347,27 +347,34 @@ You can pass either a card ID or a Basecamp URL:
 }
 
 func resolveAssigneeID(ctx context.Context, app *appctx.App, input string) (int64, error) {
+	return resolvePersonRoleID(ctx, app, input, "Assignee")
+}
+
+// resolvePersonRoleID resolves a single person name or ID. The role label
+// ("Assignee", "Completion subscriber", …) names the person's role in error
+// messages so callers surface the flag the user actually passed.
+func resolvePersonRoleID(ctx context.Context, app *appctx.App, input, role string) (int64, error) {
 	input = strings.TrimSpace(input)
 	if input == "" {
- return 0, output.ErrUsage("Assignee cannot be empty")
+ return 0, output.ErrUsage(fmt.Sprintf("%s cannot be empty", role))
 	}
 
 	if id, err := strconv.ParseInt(input, 10, 64); err == nil {
  if id <= 0 {
- return 0, output.ErrUsage("Assignee ID must be a positive number")
+ return 0, output.ErrUsage(fmt.Sprintf("%s ID must be a positive number", role))
  }
  return id, nil
 	}
 	resolvedID, _, err := app.Names.ResolvePerson(ctx, input)
 	if err != nil {
- return 0, fmt.Errorf("failed to resolve assignee '%s': %w", input, err)
+ return 0, fmt.Errorf("failed to resolve %s '%s': %w", strings.ToLower(role), input, err)
 	}
 	id, err := strconv.ParseInt(resolvedID, 10, 64)
 	if err != nil {
  return 0, fmt.Errorf("invalid resolved ID '%s': %w", resolvedID, err)
 	}
 	if id <= 0 {
- return 0, fmt.Errorf("resolved assignee ID for '%s' is not valid: %d", input, id)
+ return 0, fmt.Errorf("resolved %s ID for '%s' is not valid: %d", strings.ToLower(role), input, id)
 	}
 	return id, nil
 }
@@ -2460,6 +2467,12 @@ func resolveColumn(columns []basecamp.CardColumn, identifier string) int64 {
 }
 
 func resolveAssigneeIDs(ctx context.Context, app *appctx.App, input string) ([]int64, error) {
+	return resolvePersonRoleIDs(ctx, app, input, "Assignee")
+}
+
+// resolvePersonRoleIDs resolves a comma-separated list of person names or IDs,
+// labeling errors with the given role (see resolvePersonRoleID).
+func resolvePersonRoleIDs(ctx context.Context, app *appctx.App, input, role string) ([]int64, error) {
 	parts := strings.Split(input, ",")
 	ids := make([]int64, 0, len(parts))
 
@@ -2469,15 +2482,15 @@ func resolveAssigneeIDs(ctx context.Context, app *appctx.App, input string) ([]i
  continue
  }
 
- id, err := resolveAssigneeID(ctx, app, part)
+ id, err := resolvePersonRoleID(ctx, app, part, role)
  if err != nil {
  return nil, err
  }
  ids = append(ids, id)
 	}
 
 	if len(ids) == 0 {
- return nil, output.ErrUsage("No valid assignees provided")
+ return nil, output.ErrUsage(fmt.Sprintf("No valid %ss provided", strings.ToLower(role)))
 	}
 
 	return ids, nil

internal/commands/todos.go

@@ -766,6 +766,7 @@ func newTodosCreateCmd() *cobra.Command {
 	var due string
 	var description string
 	var attachFiles []string
+	var notifyOnCompletion string
 
 	cmd := &cobra.Command{
  Use: "create <content>",
@@ -881,6 +882,13 @@ func newTodosCreateCmd() *cobra.Command {
  assigneeIDInt, _ := strconv.ParseInt(assigneeID, 10, 64)
  req.AssigneeIDs = []int64{assigneeIDInt}
  }
+ if strings.TrimSpace(notifyOnCompletion) != "" {
+ subscriberIDs, err := resolveCompletionSubscriberIDs(cmd.Context(), app, notifyOnCompletion)
+ if err != nil {
+ return err
+ }
+ req.CompletionSubscriberIDs = subscriberIDs
+ }
 
  todolistID, err := strconv.ParseInt(resolvedTodolist, 10, 64)
  if err != nil {
@@ -925,13 +933,15 @@ func newTodosCreateCmd() *cobra.Command {
 	cmd.Flags().StringVarP(&due, "due", "d", "", "Due date (YYYY-MM-DD)")
 	cmd.Flags().StringVar(&description, "description", "", "Extended description (Markdown)")
 	cmd.Flags().StringArrayVar(&attachFiles, "attach", nil, "Attach file (repeatable)")
+	cmd.Flags().StringVar(&notifyOnCompletion, "notify-on-completion", "", "People to notify when done (names or IDs, comma-separated)")
 
 	// Register tab completion for flags
 	completer := completion.NewCompleter(nil)
 	_ = cmd.RegisterFlagCompletionFunc("project", completer.ProjectNameCompletion())
 	_ = cmd.RegisterFlagCompletionFunc("in", completer.ProjectNameCompletion())
 	_ = cmd.RegisterFlagCompletionFunc("assignee", completer.PeopleNameCompletion())
 	_ = cmd.RegisterFlagCompletionFunc("to", completer.PeopleNameCompletion())
+	_ = cmd.RegisterFlagCompletionFunc("notify-on-completion", completer.PeopleNameCompletion())
 
 	return cmd
 }
@@ -946,6 +956,8 @@ func newTodosUpdateCmd() *cobra.Command {
 	var noDue bool
 	var noStartsOn bool
 	var noDescription bool
+	var notifyOnCompletion string
+	var noNotifyOnCompletion bool
 
 	cmd := &cobra.Command{
  Use: "update <id|url> [title]",
@@ -961,7 +973,11 @@ You can pass either a todo ID or a Basecamp URL:
 Clear a field by passing its --no- flag or an empty value:
  basecamp todos update 789 --no-due
  basecamp todos update 789 --due ""
- basecamp todos update 789 --no-description`,
+ basecamp todos update 789 --no-description
+
+Set or clear the people notified when the todo is completed:
+ basecamp todos update 789 --notify-on-completion "Jane Smith,Bob"
+ basecamp todos update 789 --no-notify-on-completion`,
  RunE: func(cmd *cobra.Command, args []string) error {
  if len(args) == 0 {
  return missingArg(cmd, "<id|url>")
@@ -977,11 +993,17 @@ Clear a field by passing its --no- flag or an empty value:
  if noDescription && strings.TrimSpace(description) != "" {
  return output.ErrUsage("--no-description and --description cannot be used together")
  }
+ if noNotifyOnCompletion && strings.TrimSpace(notifyOnCompletion) != "" {
+ return output.ErrUsage("--no-notify-on-completion and --notify-on-completion cannot be used together")
+ }
  // Detect clear intent: explicit --no-X flag or empty value via --X ""
  clearDue := noDue || (cmd.Flags().Changed("due") && strings.TrimSpace(due) == "")
  clearStarts := noStartsOn || (cmd.Flags().Changed("starts-on") && strings.TrimSpace(startsOn) == "")
  clearDescription := noDescription || (cmd.Flags().Changed("description") && strings.TrimSpace(description) == "")
  needsClear := clearDue || clearStarts || clearDescription
+ // Subscriber clearing works by omission in both branches, so it
+ // doesn't force the raw-PUT clear branch.
+ clearSubscribers := noNotifyOnCompletion || (cmd.Flags().Changed("notify-on-completion") && strings.TrimSpace(notifyOnCompletion) == "")
 
  // Clearing due while setting starts is contradictory (Basecamp enforces starts <= due)
  if clearDue && strings.TrimSpace(startsOn) != "" {
@@ -999,12 +1021,13 @@ Clear a field by passing its --no- flag or an empty value:
 
  // No-op guard: at least one effective field required
  assigneeChanged := (cmd.Flags().Changed("assignee") || cmd.Flags().Changed("to")) && strings.TrimSpace(assignee) != ""
+ subscribersChanged := cmd.Flags().Changed("notify-on-completion") && strings.TrimSpace(notifyOnCompletion) != ""
  if strings.TrimSpace(effectiveTitle) == "" &&
  strings.TrimSpace(description) == "" &&
  strings.TrimSpace(due) == "" && strings.TrimSpace(startsOn) == "" &&
- !assigneeChanged &&
+ !assigneeChanged && !subscribersChanged &&
  (!cmd.Flags().Changed("notify") || !notify) &&
- !needsClear {
+ !needsClear && !clearSubscribers {
  return noChanges(cmd)
  }
 
@@ -1100,6 +1123,26 @@ Clear a field by passing its --no- flag or an empty value:
  body["assignee_ids"] = ids
  }
 
+ // Completion subscribers: the SDK's Todo model drops them, so
+ // existingTodo can't supply them — set explicitly, clear by
+ // omission, or preserve via a raw read that must succeed
+ // before any PUT (fail closed).
+ if subscribersChanged {
+ subscriberIDs, err := resolveCompletionSubscriberIDs(cmd.Context(), app, notifyOnCompletion)
+ if err != nil {
+ return err
+ }
+ body["completion_subscriber_ids"] = subscriberIDs
+ } else if !clearSubscribers {
+ subscriberIDs, err := completionSubscriberIDs(cmd.Context(), app, todoID)
+ if err != nil {
+ return err
+ }
+ if len(subscriberIDs) > 0 {
+ body["completion_subscriber_ids"] = subscriberIDs
+ }
+ }
+
  if cmd.Flags().Changed("notify") && notify {
  body["notify"] = true
  }
@@ -1166,6 +1209,25 @@ Clear a field by passing its --no- flag or an empty value:
  }
  req.AssigneeIDs = assigneeIDs
  }
+ // Completion subscribers: the SDK's Todo model drops them, so
+ // existingTodo can't supply them — set explicitly, clear by
+ // omission (nil), or preserve via a raw read that must succeed
+ // before any PUT (fail closed).
+ if subscribersChanged {
+ subscriberIDs, err := resolveCompletionSubscriberIDs(cmd.Context(), app, notifyOnCompletion)
+ if err != nil {
+ return err
+ }
+ req.CompletionSubscriberIDs = subscriberIDs
+ } else if !clearSubscribers {
+ subscriberIDs, err := completionSubscriberIDs(cmd.Context(), app, todoID)
+ if err != nil {
+ return err
+ }
+ if len(subscriberIDs) > 0 {
+ req.CompletionSubscriberIDs = subscriberIDs
+ }
+ }
  if cmd.Flags().Changed("notify") && notify {
  req.Notify = true
  }
@@ -1205,15 +1267,61 @@ Clear a field by passing its --no- flag or an empty value:
 	cmd.Flags().BoolVar(&noDue, "no-due", false, "Clear the due date")
 	cmd.Flags().BoolVar(&noStartsOn, "no-starts-on", false, "Clear the start date")
 	cmd.Flags().BoolVar(&noDescription, "no-description", false, "Clear the description")
+	cmd.Flags().StringVar(&notifyOnCompletion, "notify-on-completion", "", "People to notify when done (names or IDs, comma-separated)")
+	cmd.Flags().BoolVar(&noNotifyOnCompletion, "no-notify-on-completion", false, "Clear the people notified when done")
 
-	// Register tab completion for assignee flags
+	// Register tab completion for people flags
 	completer := completion.NewCompleter(nil)
 	_ = cmd.RegisterFlagCompletionFunc("assignee", completer.PeopleNameCompletion())
 	_ = cmd.RegisterFlagCompletionFunc("to", completer.PeopleNameCompletion())
+	_ = cmd.RegisterFlagCompletionFunc("notify-on-completion", completer.PeopleNameCompletion())
 
 	return cmd
 }
 
+// resolveCompletionSubscriberIDs resolves --notify-on-completion values
+// (comma-separated names or IDs) with completion-subscriber wording in errors.
+func resolveCompletionSubscriberIDs(ctx context.Context, app *appctx.App, input string) ([]int64, error) {
+	return resolvePersonRoleIDs(ctx, app, input, "Completion subscriber")
+}
+
+// completionSubscriberIDs reads the current completion subscriber ids via a raw
+// GET of /todos/{id}.json. The SDK's Todo model drops completion_subscribers in
+// todoFromGenerated (basecamp/basecamp-sdk#355), so a raw read is the only way
+// to preserve them across the replace-semantics PUT (#538). Delete once the SDK
+// round-trips the field.
+//
+// Fails closed: a missing or null completion_subscribers key, a malformed
+// response, or a failed GET all return an error — proceeding without knowing
+// the current subscribers would silently clear them.
+func completionSubscriberIDs(ctx context.Context, app *appctx.App, todoID int64) ([]int64, error) {
+	resp, err := app.Account().Get(ctx, fmt.Sprintf("/todos/%d.json", todoID))
+	if err != nil {
+ return nil, fmt.Errorf("failed to read current completion subscribers for todo %d: %w", todoID, convertSDKError(err))
+	}
+
+	var raw struct {
+ CompletionSubscribers *[]struct {
+ ID int64 `json:"id"`
+ } `json:"completion_subscribers"`
+	}
+	if err := resp.UnmarshalData(&raw); err != nil {
+ return nil, fmt.Errorf("failed to parse completion subscribers for todo %d: %w", todoID, err)
+	}
+	if raw.CompletionSubscribers == nil {
+ return nil, fmt.Errorf("cannot verify current completion subscribers for todo %d: response missing completion_subscribers", todoID)
+	}
+
+	ids := make([]int64, len(*raw.CompletionSubscribers))
+	for i, s := range *raw.CompletionSubscribers {
+ if s.ID <= 0 {
+ return nil, fmt.Errorf("cannot verify current completion subscribers for todo %d: subscriber with missing or invalid id", todoID)
+ }
+ ids[i] = s.ID
+	}
+	return ids, nil
+}
+
 func newTodosCompleteCmd() *cobra.Command {
 	cmd := &cobra.Command{
  Use: "complete <id|url>...",