Merge branch 'claudedo/87105f5ec4f44af4ae6089cd2e153e3c'

src/ClaudeDo.Data/CLAUDE.md

@@ -13,7 +13,7 @@ Shared data layer: models, repositories, SQLite infrastructure, and git operatio
 - **DailyNoteEntity** — Id, Date (DateOnly), Text, SortOrder, CreatedAt → table `daily_notes`
 - **WeekReportEntity** — Id, StartDate/EndDate (DateOnly), Markdown, GeneratedAt → table `week_reports`, unique index on (start_date, end_date)
 - **TaskAttachmentEntity** — Id, TaskId (FK to tasks, ON DELETE CASCADE), FileName, ByteSize, CreatedAt → table `task_attachments`
-- **AppSettingsEntity** also carries `ReportExcludedPaths` (string?, JSON array of excluded path prefixes, column `report_excluded_paths`), `StandupWeekday` (int DayOfWeek, default Wednesday, column `standup_weekday`), and `DailyPrepMaxTasks` (int, default 5, column `daily_prep_max_tasks` — hard cap on how many open tasks the daily-prep / "Prime Claude" feature may place in MyDay) , `ModelPresets` (string?, JSON array of `ModelPreset` rows, column `model_presets` — `AppSettingsRepository.GetAsync` backfills shipping defaults into this column on the first read after it's null, so it's never null once a run has started), `MaxTurnsCeiling` (int, default 80, column `max_turns_ceiling` — hard ceiling every resolved max-turns value (task/list/global) is clamped to before a run starts; `AppSettingsRepository.UpdateAsync` clamps it to a minimum of 1), and `UsageGateFiveHourPct` / `UsageGateSevenDayPct` (int, defaults 80/90, columns `usage_gate_five_hour_pct` / `usage_gate_seven_day_pct` — percentage of the 5h/7d Claude usage window at which the autonomous queue pauses; `0` = gate off; `AppSettingsRepository.UpdateAsync` clamps both to 0..100). `DefaultMaxTurns` default was lowered from 100 to 40 (entity default + `AddMaxTurnsCeiling` migration backfill on the seeded row).
+- **AppSettingsEntity** also carries `ReportExcludedPaths` (string?, JSON array of excluded path prefixes, column `report_excluded_paths`), `StandupWeekday` (int DayOfWeek, default Wednesday, column `standup_weekday`), and `DailyPrepMaxTasks` (int, default 5, column `daily_prep_max_tasks` — hard cap on how many open tasks the daily-prep / "Prime Claude" feature may place in MyDay) , `ModelPresets` (string?, JSON array of `ModelPreset` rows, column `model_presets` — `AppSettingsRepository.GetAsync` backfills shipping defaults into this column on the first read after it's null, so it's never null once a run has started), `MaxTurnsCeiling` (int, default 80, column `max_turns_ceiling` — hard ceiling every resolved max-turns value (task/list/global) is clamped to before a run starts; `AppSettingsRepository.UpdateAsync` clamps it to a minimum of 1), `UsageGateFiveHourPct` / `UsageGateSevenDayPct` (int, defaults 80/90, columns `usage_gate_five_hour_pct` / `usage_gate_seven_day_pct` — percentage of the 5h/7d Claude usage window at which the autonomous queue pauses; `0` = gate off; `AppSettingsRepository.UpdateAsync` clamps both to 0..100), and `UsageThrottleSoftPct` / `UsageThrottleHardPct` (int, defaults 50/65, columns `usage_throttle_soft_pct` / `usage_throttle_hard_pct` — intermediate staging thresholds below the hard gate above, at which the queue's effective parallelism steps down to 2 then 1 slot; see `Worker/CLAUDE.md` → `UsageThrottle`; `0` = that stage off; also clamped 0..100). `DefaultMaxTurns` default was lowered from 100 to 40 (entity default + `AddMaxTurnsCeiling` migration backfill on the seeded row).
 - **ModelPresets** / **ModelPreset** — per-model run defaults (`Model`, `Effort`, `MaxTurns`): one row per `ModelRegistry.Aliases` entry, supplying the **global** effort and max-turns defaults. `Parse`/`Serialize` normalize (unknown models dropped, missing aliases filled from `Defaults`, effort validated, turns clamped 1–200) and never throw — a malformed settings row must not stop a run. `For(presets, model, fallbackMaxTurns = 30)` always returns a usable row: `model` is resolved through `ModelRegistry.TryNormalizeAlias` first, so a full CLI model id (e.g. `claude-sonnet-4-6`) still hits its alias's preset row instead of missing every lookup and falling through; only a model that normalizes to nothing recognized falls back to a synthesized row (`EffortRegistry.DefaultLevel` + `fallbackMaxTurns` — callers pass `AppSettings.DefaultMaxTurns` here so that setting has a real effect instead of a hardcoded number). Ship defaults: haiku medium/20, sonnet high/30, opus high/40, fable high/25.
 - **ModelRegistry.TryNormalizeAlias** — non-throwing counterpart to `NormalizeAlias` for the run path: exact alias match, then substring match against a full model id, else `null`. Never throws, unlike `NormalizeAlias` (which stays the strict, throwing validator for `add_task`/planning model input).
 - **EffortRegistry** — the `--effort` levels (`low|medium|high|xhigh|max`) + `NormalizeLevel` (blank → null = don't pass the flag)
@@ -45,7 +45,7 @@ All repositories use EF Core LINQ queries via `ClaudeDoDbContext`. The atomic `Q
 
 ## Schema
 
-Tables: `lists`, `tasks`, `worktrees`, `list_config`, `task_runs`, `subtasks`, `app_settings`, `prime_schedules`, `daily_notes`, `week_reports`, `task_attachments`. Managed by EF Core migrations in the `Migrations/` folder. The `tasks` table holds `status`, `planning_phase` (default `none`), and `blocked_by_task_id` (FK to `tasks.id`, `ON DELETE SET NULL`). Migration `WeeklyReport` added `daily_notes`, `week_reports`, and the two new `app_settings` columns. Migration `DailyPrepMaxTasks` added the `daily_prep_max_tasks` column to `app_settings` (no new tables). Migration `AddTaskAttachments` created the `task_attachments` table. Migration `AddModelPresetsAndManualFlag` added `app_settings.model_presets` plus the `is_manual` flags on `tasks` and `lists`. Migration `AddHandlerCommitRange` added the nullable `handler_base_commit`/`handler_head_commit` columns to `tasks`. Migration `AddUsageGateAndRunModel` added `app_settings.usage_gate_five_hour_pct`/`usage_gate_seven_day_pct` (defaults 80/90) and the nullable `task_runs.model` column. Migration `AddWorktreeMergeCommit` added the nullable `worktrees.merge_commit` column. Migration `AddVerifyCommand` added the nullable `list_config.verify_command` column. Migration `AddMaxTurnsCeiling` added `app_settings.max_turns_ceiling` (default 80) and lowered `default_max_turns`'s default/seeded value from 100 to 40. Migration `AddRunCacheTokens` added the nullable `task_runs.cache_read_tokens`/`cache_write_tokens` columns. `TaskRepository.DeleteAsync` and `ListRepository.DeleteAsync` also delete the on-disk attachment dir(s) via an optional `AttachmentStore` ctor param (defaults to the production store).
+Tables: `lists`, `tasks`, `worktrees`, `list_config`, `task_runs`, `subtasks`, `app_settings`, `prime_schedules`, `daily_notes`, `week_reports`, `task_attachments`. Managed by EF Core migrations in the `Migrations/` folder. The `tasks` table holds `status`, `planning_phase` (default `none`), and `blocked_by_task_id` (FK to `tasks.id`, `ON DELETE SET NULL`). Migration `WeeklyReport` added `daily_notes`, `week_reports`, and the two new `app_settings` columns. Migration `DailyPrepMaxTasks` added the `daily_prep_max_tasks` column to `app_settings` (no new tables). Migration `AddTaskAttachments` created the `task_attachments` table. Migration `AddModelPresetsAndManualFlag` added `app_settings.model_presets` plus the `is_manual` flags on `tasks` and `lists`. Migration `AddHandlerCommitRange` added the nullable `handler_base_commit`/`handler_head_commit` columns to `tasks`. Migration `AddUsageGateAndRunModel` added `app_settings.usage_gate_five_hour_pct`/`usage_gate_seven_day_pct` (defaults 80/90) and the nullable `task_runs.model` column. Migration `AddWorktreeMergeCommit` added the nullable `worktrees.merge_commit` column. Migration `AddVerifyCommand` added the nullable `list_config.verify_command` column. Migration `AddMaxTurnsCeiling` added `app_settings.max_turns_ceiling` (default 80) and lowered `default_max_turns`'s default/seeded value from 100 to 40. Migration `AddRunCacheTokens` added the nullable `task_runs.cache_read_tokens`/`cache_write_tokens` columns. Migration `AddUsageThrottleThresholds` added `app_settings.usage_throttle_soft_pct`/`usage_throttle_hard_pct` (defaults 50/65). `TaskRepository.DeleteAsync` and `ListRepository.DeleteAsync` also delete the on-disk attachment dir(s) via an optional `AttachmentStore` ctor param (defaults to the production store).
 
 ## Conventions
 

src/ClaudeDo.Data/Configuration/AppSettingsEntityConfiguration.cs

@@ -55,6 +55,11 @@ public class AppSettingsEntityConfiguration : IEntityTypeConfiguration<AppSettin
         builder.Property(s => s.UsageGateSevenDayPct)
             .HasColumnName("usage_gate_seven_day_pct").IsRequired().HasDefaultValue(90);
 
+        builder.Property(s => s.UsageThrottleSoftPct)
+            .HasColumnName("usage_throttle_soft_pct").IsRequired().HasDefaultValue(50);
+        builder.Property(s => s.UsageThrottleHardPct)
+            .HasColumnName("usage_throttle_hard_pct").IsRequired().HasDefaultValue(65);
+
         builder.HasData(new AppSettingsEntity { Id = AppSettingsEntity.SingletonId });
     }
 }

src/ClaudeDo.Data/Migrations/20260805133429_AddUsageThrottleThresholds.Designer.cs

@@ -0,0 +1,850 @@
+// <auto-generated />
+using System;
+using ClaudeDo.Data;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+
+#nullable disable
+
+namespace ClaudeDo.Data.Migrations
+{
+    [DbContext(typeof(ClaudeDoDbContext))]
+    [Migration("20260805133429_AddUsageThrottleThresholds")]
+    partial class AddUsageThrottleThresholds
+    {
+        /// <inheritdoc />
+        protected override void BuildTargetModel(ModelBuilder modelBuilder)
+        {
+#pragma warning disable 612, 618
+            modelBuilder.HasAnnotation("ProductVersion", "8.0.11");
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.AppSettingsEntity", b =>
+                {
+                    b.Property<int>("Id")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("id");
+
+                    b.Property<string>("CentralWorktreeRoot")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("central_worktree_root");
+
+                    b.Property<int>("DailyPrepMaxTasks")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(5)
+                        .HasColumnName("daily_prep_max_tasks");
+
+                    b.Property<string>("DefaultClaudeInstructions")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("")
+                        .HasColumnName("default_claude_instructions");
+
+                    b.Property<int>("DefaultMaxTurns")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(30)
+                        .HasColumnName("default_max_turns");
+
+                    b.Property<string>("DefaultModel")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("sonnet")
+                        .HasColumnName("default_model");
+
+                    b.Property<string>("DefaultPermissionMode")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("bypassPermissions")
+                        .HasColumnName("default_permission_mode");
+
+                    b.Property<int>("MaxParallelExecutions")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(1)
+                        .HasColumnName("max_parallel_executions");
+
+                    b.Property<string>("ModelPresets")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("model_presets");
+
+                    b.Property<string>("RepoImportFolders")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("repo_import_folders");
+
+                    b.Property<string>("ReportExcludedPaths")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("report_excluded_paths");
+
+                    b.Property<string>("SessionSkills")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("session_skills");
+
+                    b.Property<int>("StandupWeekday")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(3)
+                        .HasColumnName("standup_weekday");
+
+                    b.Property<int>("UsageGateFiveHourPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(80)
+                        .HasColumnName("usage_gate_five_hour_pct");
+
+                    b.Property<int>("UsageGateSevenDayPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(90)
+                        .HasColumnName("usage_gate_seven_day_pct");
+
+                    b.Property<int>("UsageThrottleHardPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(65)
+                        .HasColumnName("usage_throttle_hard_pct");
+
+                    b.Property<int>("UsageThrottleSoftPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(50)
+                        .HasColumnName("usage_throttle_soft_pct");
+
+                    b.Property<int>("WorktreeAutoCleanupDays")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(7)
+                        .HasColumnName("worktree_auto_cleanup_days");
+
+                    b.Property<bool>("WorktreeAutoCleanupEnabled")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("worktree_auto_cleanup_enabled");
+
+                    b.Property<string>("WorktreeStrategy")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("sibling")
+                        .HasColumnName("worktree_strategy");
+
+                    b.HasKey("Id");
+
+                    b.ToTable("app_settings", (string)null);
+
+                    b.HasData(
+                        new
+                        {
+                            Id = 1,
+                            DailyPrepMaxTasks = 5,
+                            DefaultClaudeInstructions = "",
+                            DefaultMaxTurns = 100,
+                            DefaultModel = "sonnet",
+                            DefaultPermissionMode = "auto",
+                            MaxParallelExecutions = 1,
+                            StandupWeekday = 3,
+                            UsageGateFiveHourPct = 80,
+                            UsageGateSevenDayPct = 90,
+                            UsageThrottleHardPct = 65,
+                            UsageThrottleSoftPct = 50,
+                            WorktreeAutoCleanupDays = 7,
+                            WorktreeAutoCleanupEnabled = false,
+                            WorktreeStrategy = "sibling"
+                        });
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.DailyNoteEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<DateOnly>("Date")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("note_date");
+
+                    b.Property<int>("SortOrder")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("sort_order");
+
+                    b.Property<string>("Text")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("text");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("Date");
+
+                    b.ToTable("daily_notes", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.ListConfigEntity", b =>
+                {
+                    b.Property<string>("ListId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("list_id");
+
+                    b.Property<string>("AgentPath")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("agent_path");
+
+                    b.Property<int?>("MaxTurns")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("max_turns");
+
+                    b.Property<string>("Model")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("model");
+
+                    b.Property<string>("SessionSkills")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("session_skills");
+
+                    b.Property<string>("SystemPrompt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("system_prompt");
+
+                    b.Property<string>("VerifyCommand")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("verify_command");
+
+                    b.HasKey("ListId");
+
+                    b.ToTable("list_config", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.ListEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<string>("DefaultCommitType")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("chore")
+                        .HasColumnName("default_commit_type");
+
+                    b.Property<bool>("IsManual")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("is_manual");
+
+                    b.Property<string>("Name")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("name");
+
+                    b.Property<int>("SortOrder")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(0)
+                        .HasColumnName("sort_order");
+
+                    b.Property<string>("WorkingDir")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("working_dir");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("SortOrder")
+                        .HasDatabaseName("idx_lists_sort");
+
+                    b.ToTable("lists", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.PrimeScheduleEntity", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<DateTimeOffset>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<int>("Days")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(31)
+                        .HasColumnName("days_of_week");
+
+                    b.Property<bool>("Enabled")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(true)
+                        .HasColumnName("enabled");
+
+                    b.Property<DateTimeOffset?>("LastRunAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("last_run_at");
+
+                    b.Property<string>("PromptOverride")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("prompt_override");
+
+                    b.Property<TimeSpan>("TimeOfDay")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("time_of_day");
+
+                    b.HasKey("Id");
+
+                    b.ToTable("prime_schedules", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.SessionSkillEntity", b =>
+                {
+                    b.Property<string>("Name")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("name");
+
+                    b.Property<DateTimeOffset>("AddedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("added_at");
+
+                    b.Property<string>("Description")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("description");
+
+                    b.Property<string>("PinnedRef")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("pinned_ref");
+
+                    b.Property<string>("SourceUrl")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("source_url");
+
+                    b.Property<string>("Subpath")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("subpath");
+
+                    b.HasKey("Name");
+
+                    b.ToTable("session_skills", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.SubtaskEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<bool>("Completed")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("completed");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<int>("OrderNum")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("order_num");
+
+                    b.Property<string>("TaskId")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("task_id");
+
+                    b.Property<string>("Title")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("title");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("TaskId")
+                        .HasDatabaseName("idx_subtasks_task_id");
+
+                    b.ToTable("subtasks", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskAttachmentEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<long>("ByteSize")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("byte_size");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<string>("FileName")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("file_name");
+
+                    b.Property<string>("TaskId")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("task_id");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("TaskId")
+                        .HasDatabaseName("idx_task_attachments_task_id");
+
+                    b.ToTable("task_attachments", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<string>("AgentPath")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("agent_path");
+
+                    b.Property<string>("BlockedByTaskId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("blocked_by_task_id");
+
+                    b.Property<string>("CommitType")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("chore")
+                        .HasColumnName("commit_type");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<string>("CreatedBy")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_by");
+
+                    b.Property<string>("Description")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("description");
+
+                    b.Property<DateTime?>("FinishedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("finished_at");
+
+                    b.Property<string>("HandlerBaseCommit")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("handler_base_commit");
+
+                    b.Property<string>("HandlerHeadCommit")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("handler_head_commit");
+
+                    b.Property<bool>("IsManual")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("is_manual");
+
+                    b.Property<bool>("IsMyDay")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("is_my_day");
+
+                    b.Property<bool>("IsStarred")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("is_starred");
+
+                    b.Property<string>("ListId")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("list_id");
+
+                    b.Property<string>("LogPath")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("log_path");
+
+                    b.Property<int?>("MaxTurns")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("max_turns");
+
+                    b.Property<string>("Model")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("model");
+
+                    b.Property<string>("Notes")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("notes");
+
+                    b.Property<string>("ParentTaskId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("parent_task_id");
+
+                    b.Property<DateTime?>("PlanningFinalizedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("planning_finalized_at");
+
+                    b.Property<string>("PlanningPhase")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("none")
+                        .HasColumnName("planning_phase");
+
+                    b.Property<string>("PlanningSessionId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("planning_session_id");
+
+                    b.Property<string>("PlanningSessionToken")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("planning_session_token");
+
+                    b.Property<string>("Result")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("result");
+
+                    b.Property<string>("ReviewFeedback")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("review_feedback");
+
+                    b.Property<int>("RoadblockCount")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(0)
+                        .HasColumnName("roadblock_count");
+
+                    b.Property<DateTime?>("ScheduledFor")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("scheduled_for");
+
+                    b.Property<string>("SessionSkills")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("session_skills");
+
+                    b.Property<int>("SortOrder")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(0)
+                        .HasColumnName("sort_order");
+
+                    b.Property<DateTime?>("StartedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("started_at");
+
+                    b.Property<string>("Status")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("status");
+
+                    b.Property<string>("SystemPrompt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("system_prompt");
+
+                    b.Property<string>("Title")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("title");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("BlockedByTaskId")
+                        .HasDatabaseName("idx_tasks_blocked_by");
+
+                    b.HasIndex("ListId")
+                        .HasDatabaseName("idx_tasks_list_id");
+
+                    b.HasIndex("ParentTaskId")
+                        .HasDatabaseName("idx_tasks_parent_task_id");
+
+                    b.HasIndex("Status")
+                        .HasDatabaseName("idx_tasks_status");
+
+                    b.HasIndex("ListId", "SortOrder")
+                        .HasDatabaseName("idx_tasks_list_sort");
+
+                    b.ToTable("tasks", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskRunEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<string>("ErrorMarkdown")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("error_markdown");
+
+                    b.Property<int?>("ExitCode")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("exit_code");
+
+                    b.Property<DateTime?>("FinishedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("finished_at");
+
+                    b.Property<bool>("IsRetry")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(false)
+                        .HasColumnName("is_retry");
+
+                    b.Property<string>("LogPath")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("log_path");
+
+                    b.Property<string>("Model")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("model");
+
+                    b.Property<string>("Prompt")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("prompt");
+
+                    b.Property<string>("ResultMarkdown")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("result_markdown");
+
+                    b.Property<int>("RunNumber")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("run_number");
+
+                    b.Property<string>("SessionId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("session_id");
+
+                    b.Property<DateTime?>("StartedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("started_at");
+
+                    b.Property<string>("StructuredOutputJson")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("structured_output");
+
+                    b.Property<string>("TaskId")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("task_id");
+
+                    b.Property<int?>("TokensIn")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("tokens_in");
+
+                    b.Property<int?>("TokensOut")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("tokens_out");
+
+                    b.Property<int?>("TurnCount")
+                        .HasColumnType("INTEGER")
+                        .HasColumnName("turn_count");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("TaskId")
+                        .HasDatabaseName("idx_task_runs_task_id");
+
+                    b.ToTable("task_runs", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.WeekReportEntity", b =>
+                {
+                    b.Property<string>("Id")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("id");
+
+                    b.Property<DateOnly>("EndDate")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("end_date");
+
+                    b.Property<DateTime>("GeneratedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("generated_at");
+
+                    b.Property<string>("Markdown")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("markdown");
+
+                    b.Property<DateOnly>("StartDate")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("start_date");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("StartDate", "EndDate")
+                        .IsUnique();
+
+                    b.ToTable("week_reports", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.WorktreeEntity", b =>
+                {
+                    b.Property<string>("TaskId")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("task_id");
+
+                    b.Property<string>("BaseCommit")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("base_commit");
+
+                    b.Property<string>("BranchName")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("branch_name");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("created_at");
+
+                    b.Property<string>("DiffStat")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("diff_stat");
+
+                    b.Property<string>("HeadCommit")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("head_commit");
+
+                    b.Property<string>("MergeCommit")
+                        .HasColumnType("TEXT")
+                        .HasColumnName("merge_commit");
+
+                    b.Property<string>("Path")
+                        .IsRequired()
+                        .HasColumnType("TEXT")
+                        .HasColumnName("path");
+
+                    b.Property<string>("State")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("TEXT")
+                        .HasDefaultValue("active")
+                        .HasColumnName("state");
+
+                    b.HasKey("TaskId");
+
+                    b.ToTable("worktrees", (string)null);
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.ListConfigEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.ListEntity", "List")
+                        .WithOne("Config")
+                        .HasForeignKey("ClaudeDo.Data.Models.ListConfigEntity", "ListId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("List");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.SubtaskEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", "Task")
+                        .WithMany("Subtasks")
+                        .HasForeignKey("TaskId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Task");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskAttachmentEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", "Task")
+                        .WithMany()
+                        .HasForeignKey("TaskId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Task");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", null)
+                        .WithMany()
+                        .HasForeignKey("BlockedByTaskId")
+                        .OnDelete(DeleteBehavior.SetNull);
+
+                    b.HasOne("ClaudeDo.Data.Models.ListEntity", "List")
+                        .WithMany("Tasks")
+                        .HasForeignKey("ListId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", "Parent")
+                        .WithMany("Children")
+                        .HasForeignKey("ParentTaskId")
+                        .OnDelete(DeleteBehavior.Restrict);
+
+                    b.Navigation("List");
+
+                    b.Navigation("Parent");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskRunEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", "Task")
+                        .WithMany("Runs")
+                        .HasForeignKey("TaskId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Task");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.WorktreeEntity", b =>
+                {
+                    b.HasOne("ClaudeDo.Data.Models.TaskEntity", "Task")
+                        .WithOne("Worktree")
+                        .HasForeignKey("ClaudeDo.Data.Models.WorktreeEntity", "TaskId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Task");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.ListEntity", b =>
+                {
+                    b.Navigation("Config");
+
+                    b.Navigation("Tasks");
+                });
+
+            modelBuilder.Entity("ClaudeDo.Data.Models.TaskEntity", b =>
+                {
+                    b.Navigation("Children");
+
+                    b.Navigation("Runs");
+
+                    b.Navigation("Subtasks");
+
+                    b.Navigation("Worktree");
+                });
+#pragma warning restore 612, 618
+        }
+    }
+}

src/ClaudeDo.Data/Migrations/20260805133429_AddUsageThrottleThresholds.cs

@@ -0,0 +1,47 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace ClaudeDo.Data.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddUsageThrottleThresholds : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<int>(
+                name: "usage_throttle_hard_pct",
+                table: "app_settings",
+                type: "INTEGER",
+                nullable: false,
+                defaultValue: 65);
+
+            migrationBuilder.AddColumn<int>(
+                name: "usage_throttle_soft_pct",
+                table: "app_settings",
+                type: "INTEGER",
+                nullable: false,
+                defaultValue: 50);
+
+            migrationBuilder.UpdateData(
+                table: "app_settings",
+                keyColumn: "id",
+                keyValue: 1,
+                columns: new[] { "usage_throttle_hard_pct", "usage_throttle_soft_pct" },
+                values: new object[] { 65, 50 });
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "usage_throttle_hard_pct",
+                table: "app_settings");
+
+            migrationBuilder.DropColumn(
+                name: "usage_throttle_soft_pct",
+                table: "app_settings");
+        }
+    }
+}

src/ClaudeDo.Data/Migrations/ClaudeDoDbContextModelSnapshot.cs

@@ -106,6 +106,18 @@ namespace ClaudeDo.Data.Migrations
                         .HasDefaultValue(90)
                         .HasColumnName("usage_gate_seven_day_pct");
 
+                    b.Property<int>("UsageThrottleHardPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(65)
+                        .HasColumnName("usage_throttle_hard_pct");
+
+                    b.Property<int>("UsageThrottleSoftPct")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("INTEGER")
+                        .HasDefaultValue(50)
+                        .HasColumnName("usage_throttle_soft_pct");
+
                     b.Property<int>("WorktreeAutoCleanupDays")
                         .ValueGeneratedOnAdd()
                         .HasColumnType("INTEGER")
@@ -143,6 +155,8 @@ namespace ClaudeDo.Data.Migrations
                             StandupWeekday = 3,
                             UsageGateFiveHourPct = 80,
                             UsageGateSevenDayPct = 90,
+                            UsageThrottleHardPct = 65,
+                            UsageThrottleSoftPct = 50,
                             WorktreeAutoCleanupDays = 7,
                             WorktreeAutoCleanupEnabled = false,
                             WorktreeStrategy = "sibling"

src/ClaudeDo.Data/Models/AppSettingsEntity.cs

@@ -42,4 +42,9 @@ public sealed class AppSettingsEntity
     // Percentage of the 5h/7d Claude usage window at which the autonomous queue pauses. 0 = gate off.
     public int UsageGateFiveHourPct { get; set; } = 80;
     public int UsageGateSevenDayPct { get; set; } = 90;
+
+    // Percentage of the 5h/7d Claude usage window at which the queue starts throttling
+    // parallelism ahead of the hard gate above. 0 = that stage off.
+    public int UsageThrottleSoftPct { get; set; } = 50;
+    public int UsageThrottleHardPct { get; set; } = 65;
 }

src/ClaudeDo.Data/Repositories/AppSettingsRepository.cs

@@ -88,6 +88,8 @@ public sealed class AppSettingsRepository
         row.SessionSkills = string.IsNullOrWhiteSpace(updated.SessionSkills) ? null : updated.SessionSkills;
         row.UsageGateFiveHourPct = Math.Clamp(updated.UsageGateFiveHourPct, 0, 100);
         row.UsageGateSevenDayPct = Math.Clamp(updated.UsageGateSevenDayPct, 0, 100);
+        row.UsageThrottleSoftPct = Math.Clamp(updated.UsageThrottleSoftPct, 0, 100);
+        row.UsageThrottleHardPct = Math.Clamp(updated.UsageThrottleHardPct, 0, 100);
 
         await _context.SaveChangesAsync(ct);
     }

src/ClaudeDo.Localization/locales/de.json

@@ -434,6 +434,7 @@
       "staleFormat": "Werte veraltet (Stand {0})",
       "staleGateHint": "Das Gate greift in diesem Zustand nicht.",
       "gateBlockedFormat": "Queue pausiert — {0}",
+      "throttleFormat": "Queue gedrosselt: {0}/{1} Slots ({2})",
       "resetIn": "Reset in {0}",
       "gaugeSession": "Session (5 Std.)",
       "gaugeWeeklyAll": "Woche (alle Modelle)",
@@ -619,7 +620,8 @@
       "durationMinutes": "{0} m",
       "blockedReason": "Blockiert: {0}",
       "stale": "veraltet (Stand {0})",
-      "lastError": "Letzter Fehler: {0}"
+      "lastError": "Letzter Fehler: {0}",
+      "throttled": "Gedrosselt: {0}/{1} Slots ({2})"
     }
   }
 }

src/ClaudeDo.Localization/locales/en.json

@@ -434,6 +434,7 @@
       "staleFormat": "Values stale (as of {0})",
       "staleGateHint": "The gate does not apply while values are stale.",
       "gateBlockedFormat": "Queue paused — {0}",
+      "throttleFormat": "Queue throttled: {0}/{1} slots ({2})",
       "resetIn": "Reset in {0}",
       "gaugeSession": "Session (5h)",
       "gaugeWeeklyAll": "Week (all models)",
@@ -619,7 +620,8 @@
       "durationMinutes": "{0} m",
       "blockedReason": "Blocked: {0}",
       "stale": "stale (as of {0})",
-      "lastError": "Last error: {0}"
+      "lastError": "Last error: {0}",
+      "throttled": "Throttled: {0}/{1} slots ({2})"
     }
   }
 }

src/ClaudeDo.Ui/CLAUDE.md

@@ -39,7 +39,7 @@ Design/     — Tokens.axaml (design tokens; merged before styles) + IslandStyle
 - **DetailsIslandViewModel** — the detail pane for a bound `TaskRowViewModel`. Owns live-log streaming (`Log` via `StreamLineFormatter`), debounced title/description editing, subtasks, session-outcome/roadblock split (splits `Result` at the roadblock marker into two cards) — the ROADBLOCK card also has a reply field (`RoadblockReplyDraft`/`SendRoadblockReplyCommand`, gated by `CanReplyToRoadblock` on `LatestRunSessionId`) that resumes the session via the same `ContinueTaskAsync` transport as `ContinueCommand` but with the user's own text instead of the fixed re-run prompt; failures raise `ErrorReported`, wired by the shell into `FlashFooterError`, the three-tab work console (`output`/`git`/`session`), child surfacing (`ChildOutcomes` rows plus `ChildrenNeedingAttention`/`HasChildrenNeedingAttention` — children that failed, were cancelled, await review, or reported roadblocks — drive an attention band on the Session tab, which is only visible when `HasChildOutcomes`), and the modes: `IsNotesMode` (hosts `NotesEditorViewModel`), `IsPrepMode`, computed `IsTaskDetailVisible = !IsNotesMode && !IsPrepMode`. Three concerns are extracted into section VMs exposed as properties: **AgentConfigEditorViewModel** (scope=Task; per-task Model/MaxTurns/AgentPath overrides with `InheritedBadge` + `InheritanceResolver`, additive SystemPrompt, debounced auto-save; exposed as `AgentSettings`), **MergeSectionViewModel** (merge-target selection, mergeability indicator via `MergePreviewPresenter` over `PreviewMergeAsync`, `OpenDiffAsync` and `ReviewCombinedDiffCommand` — both build a `DiffViewerViewModel`, call `ShowDiffViewer`, and fire the `DiffViewed` callback; `HasReviewableDiff` reports whether anything is inspectable, feeding the review gate), **PrepPanelViewModel** (daily-prep panel: `PrepLog`, `PlanDayCommand` → `RunDailyPrepNowAsync`, persisted last run via `GetLastPrepLogAsync`). Attachments: `Attachments` (`ObservableCollection<AttachmentRowViewModel>`), `IsDragOver`, `DropStatus`, `CanAcceptDrop`, `AddFilesAsync`, `RemoveAttachmentCommand`; loads on task change; `ComposedPreview` includes attachment paths. Writes directly via `new AttachmentStore()` + `new TaskAttachmentRepository(ctx)`. Helper rows (`ChildOutcomeRowViewModel`, `SubtaskRowViewModel`, `LogLineViewModel`, `AttachmentRowViewModel`) live in the same file.
 - **TaskRowViewModel** / **ListNavItemViewModel** — lightweight display VMs (task row: status, planning phase, parent/blocked links, roadblock count, computed `IsDraft`/`IsPlanned`/`IsChild`/`IsPlanningParent`/`CanRefine`; plus `IsManual` (→ MANUAL badge; suppresses `CanSendToQueue`/`CanRefine`/`CanOpenPlanningSession`) and `HasInteractiveSession` (→ accent "Interactive" chip instead of "Parked"; tapping it jumps to that Mission Control pane); list row: kind Smart/Virtual/User, count, icon/dot keys, drop hints, `IsManual`).
 - **NotesEditorViewModel** — day navigator + bullet CRUD for daily notes via `INotesApi`.
-- **UsagePillViewModel** — one shared instance backs the `UsagePill` control hosted in both the footer and the Mission Control header; loads via `GetUsageSnapshotAsync` and updates live off `IWorkerClient.UsageUpdatedEvent`; derives display text, tooltip, and dot state (normal/warn/stale/blocked, mutually exclusive priority blocked > stale > warn > normal) from the shared `UsageSnapshotDto`.
+- **UsagePillViewModel** — one shared instance backs the `UsagePill` control hosted in both the footer and the Mission Control header; loads via `GetUsageSnapshotAsync` and updates live off `IWorkerClient.UsageUpdatedEvent`; derives display text, tooltip, and dot state (normal/warn/stale/blocked, mutually exclusive priority blocked > stale > warn > normal) from the shared `UsageSnapshotDto`. `IsThrottled` (effective slots below configured, and not gate-blocked) adds a tooltip line naming the effective/configured slot count and the decisive bucket (`ThrottleBucket` on the DTO — `"five_hour"`/`"seven_day"`).
 - **Modal VMs** — `SettingsModalViewModel` (four tabs: General, Worktrees, Files prompt-paths, Prime Claude incl. `DailyPrepMaxTasks` + prime-schedule rows). General hosts the per-model preset table (`ModelPresets` → `ModelPresetRowViewModel`: effort + max turns per alias) which **replaced** the single global "Max turns" field, `ListSettingsModalViewModel` (name, working dir, commit type, "manual list" flag, `VerifyCommand` (optional post-merge verify gate, own field/section — not part of `AgentConfigEditorViewModel`), delete list; hosts shared `AgentConfigEditorViewModel` as `Agent` property (scope=List) — save delegates to `Agent.SaveAsync(verifyCommand)`, since both fields land in the same `list_config` row via one `UpdateListConfig` call and would otherwise clobber each other), `RepoImportModalViewModel` (bulk-create lists from git repos found under chosen parents; already-wired repos disabled), `WeeklyReportModalViewModel` (range pickers default "since last standup weekday → today", cached per range, markdown via MarkdownView), `MergeModalViewModel` (single-task merge form, called from the diff modal), `WorktreesOverviewModalViewModel` (global/per-list worktree rows, batch merge + state ops), `UnfinishedPlanningModalViewModel` (Resume/FinalizeNow/Discard for a draft planning session), `MergeHelperSelectionModalViewModel` ("Let Claude handle it": checkbox picker over one list's non-terminal, non-manual tasks, pre-ticks the actionable ones; list-scoped only — `Configure(listId, listName)`, no global scope. Opened from the list row's context menu, which is hidden when the list has no working dir; on confirm `ListsIslandViewModel` raises `LetClaudeHandleRequested` → shell → `MissionControlViewModel.OpenMergeHelperConPtySessionAsync`, which first calls `IWorkerClient.CreateMergeHelperTaskAsync` to create one new ClaudeDo task per run in that list — `Idle`/`IsManual=true` (never queued), title/description localized (`missionControl.mergeHelperTaskTitle`/`mergeHelperTaskDescriptionHeader`), `TaskEntity.HandlerBaseCommit` stamped to the list repo's current HEAD — then opens a **task-based** ConPTY tile for it (deduped by `TaskId` like `OpenConPtySessionAsync`, not `CreateAdHoc`) running the five-phase handler prompt. The handler still merges the tasks it handles itself; the host task never gets a worktree of its own, so "Submit for review" stamps `HandlerHeadCommit` instead of committing a worktree, and the detail pane's `MergeSectionViewModel` falls back to `HandlerBaseCommit`/`HandlerHeadCommit` over the list's working dir for its diff — see `TaskEntity` in `ClaudeDo.Data/CLAUDE.md`), `WorkerConnectionModalViewModel` (offline help), `AboutModalViewModel`, `LogVisualizerViewModel` (worker logs, last 30 min, all levels + a warn/error-only filter; loads via `GetRecentLogsAsync`), `UsageMonitorModalViewModel` (opened from the usage pill; renders one gauge per row in `UsageSnapshotDto.Limits` — **dynamic**, since the fixed `seven_day_opus`/`seven_day_sonnet`-style buckets the raw Anthropic API can return are plan-dependent and come back `null` on plans that don't have them, so a fixed gauge layout would break; also shows model usage (`GetModelUsageAsync`, ClaudeDo-vs-Other split per model) and top-task usage (`GetTaskUsageAsync`) tables over a 7d/30d preset or custom date range).
 - **Diff stack** — `UnifiedDiffParser` (static; parses `git diff` output into `DiffFileViewModel`s, detecting added/deleted/renamed/binary files and per-line numbers; `Flatten` injects file-header rows for a combined single-pane view). `DiffModels.cs` holds shared types: `DiffLineViewModel`, `DiffFileViewModel`, `DiffLineKind`, `DiffFileStatus`, `SubtaskDiffRow`, `DiffTreeNodeViewModel`, `DiffTree`. `DiffViewerViewModel` is a single unified read-only diff viewer with two modes: **Files** (dirty worktree / branch-vs-base / commit-range — loads via GitService, shows a folder file-tree on the left + per-file diff pane on the right, Merge button for live branch source) and **Planning** (per-subtask diffs via `GetPlanningAggregateAsync`, subtask list left + flat diff right, combined integration-branch toggle). The Merge button opens the merge form, which routes to `ConflictResolverViewModel` on conflict. `DiffLinesView` renders per-file diff content with binary/empty placeholders.
 - **Conflicts** — `ConflictResolverViewModel` (in-app **Rider-style 3-pane merge editor** for both single-task and planning unit-merge conflicts: single-task starts the conflict merge, parses each conflicted file into stable/conflict `MergeFileSegment`s via the worker's `GetMergeConflictDocuments`; exposes the active file's three reconstructed documents — `ActiveOursText` / `ActiveResultText` / `ActiveTheirsText` (from `MergeFile.OursText/ResultText/TheirsText`; Result seeds unresolved conflicts with Ours) — plus `ActiveFile`/`SelectFileCommand` (multi-file switcher), `Current`/`Next`/`Previous` (focused-conflict nav), a per-active-file `PositionText` readout, per-block `AcceptOurs/Theirs/Both/Base` + `MergeFile.Compose`, and `CanContinue` gated on every file resolved + no binary; writes each file via `WriteConflictResolution`, continue/abort; **planning mode** via `OpenForPlanningAsync(parentId, subtaskId)` loads the current subtask's mid-merge conflicts without re-starting the merge and routes continue/abort to `ContinuePlanningMerge`/`AbortPlanningMerge`, so a unit-merge conflict re-opens the editor per subtask via the `PlanningMergeConflict` broadcast). The view (`Views/Conflicts/ConflictResolverView`) shows the whole file in three **AvaloniaEdit** panes — MAIN/ours (read-only) | editable Result | INCOMING/theirs (read-only) — with TextMate highlighting by extension (theme `StyleInclude` in `App.axaml`); a code-behind `IBackgroundRenderer` tints each conflict block (unresolved/resolved) across panes, an `IReadOnlySectionProvider` + `TextAnchor` regions keep only conflict spans editable in Result (edits flow back to the block); each unresolved conflict starts EMPTY (a thin marker bar); the between-pane gutter controls **toggle** each side in/out of the result — `›`/`‹` add MAIN/INCOMING in click order (first pick on top), clicking again removes that side — so a conflict can take main, incoming, both, or neither; a `FilesSummary` readout shows how many files still have conflicts, and the three panes share a proportional synced vertical scroll. A conflict overview ruler right of the Result pane (`ConflictMap`) maps every conflict in the file proportionally (click a tick to jump) — handy for long files. Conflict block tints live in `Tokens.axaml` (`Merge*TintBrush`). The editor is reached from review **Approve** on conflict and from the **Merge** button in the Diff window (a conflicting `MergeTask` hands off to the resolver via `RequestConflictResolution`).

src/ClaudeDo.Ui/Services/WorkerClient.cs

@@ -715,7 +715,10 @@ public sealed record UsageSnapshotDto(
     string? GateReason,
     DateTime? FetchedAtUtc,
     bool IsStale,
-    string? LastError);
+    string? LastError,
+    int ConfiguredSlots,
+    int EffectiveSlots,
+    string? ThrottleBucket);
 
 public sealed record ModelUsageRowDto(
     DateOnly Date,

src/ClaudeDo.Ui/ViewModels/Modals/UsageMonitorModalViewModel.cs

@@ -28,6 +28,8 @@ public sealed partial class UsageMonitorModalViewModel : ViewModelBase
     [NotifyPropertyChangedFor(nameof(StaleStampText))]
     [NotifyPropertyChangedFor(nameof(StaleBandText))]
     [NotifyPropertyChangedFor(nameof(GateBandText))]
+    [NotifyPropertyChangedFor(nameof(IsThrottled))]
+    [NotifyPropertyChangedFor(nameof(ThrottleBandText))]
     private UsageSnapshotDto? _snapshot;
 
     [ObservableProperty] private DateTime? _startDate;
@@ -60,6 +62,18 @@ public sealed partial class UsageMonitorModalViewModel : ViewModelBase
     public string StaleBandText => Loc.T("modals.usageMonitor.staleFormat", StaleStampText);
     public string GateBandText => GateReason is null ? "" : Loc.T("modals.usageMonitor.gateBlockedFormat", GateReason);
 
+    public bool IsThrottled => Snapshot is { } s && !IsGateBlocked && s.EffectiveSlots < s.ConfiguredSlots;
+    public string ThrottleBandText => Snapshot is not { } s || !IsThrottled
+        ? ""
+        : Loc.T("modals.usageMonitor.throttleFormat", s.EffectiveSlots, s.ConfiguredSlots, BucketLabel(s.ThrottleBucket));
+
+    private static string BucketLabel(string? bucket) => bucket switch
+    {
+        "five_hour" => Loc.T("usage.pill.fiveHourLabel"),
+        "seven_day" => Loc.T("usage.pill.sevenDayLabel"),
+        _ => "",
+    };
+
     [RelayCommand]
     private void Close()
     {

src/ClaudeDo.Ui/ViewModels/UsagePillViewModel.cs

@@ -40,6 +40,7 @@ public sealed partial class UsagePillViewModel : ViewModelBase
         OnPropertyChanged(nameof(IsWarn));
         OnPropertyChanged(nameof(IsBlocked));
         OnPropertyChanged(nameof(IsStale));
+        OnPropertyChanged(nameof(IsThrottled));
         OnPropertyChanged(nameof(Tooltip));
         OnPropertyChanged(nameof(ShowNormalDot));
         OnPropertyChanged(nameof(ShowWarnDot));
@@ -52,6 +53,8 @@ public sealed partial class UsagePillViewModel : ViewModelBase
 
     public bool IsStale => Snapshot?.IsStale == true;
 
+    public bool IsThrottled => Snapshot is { } s && !IsBlocked && s.EffectiveSlots < s.ConfiguredSlots;
+
     public bool IsWarn => Snapshot is { } s &&
         ((s.FiveHourPercent is { } five && five >= s.FiveHourThresholdPct - 10) ||
          (s.SevenDayPercent is { } seven && seven >= s.SevenDayThresholdPct - 10));
@@ -95,6 +98,8 @@ public sealed partial class UsagePillViewModel : ViewModelBase
             lines.Add(Loc.T("usage.pill.resetIn", Loc.T("usage.pill.sevenDayLabel"), FormatRemaining(sevenReset)));
         if (s.IsGateBlocked && !string.IsNullOrEmpty(s.GateReason))
             lines.Add(Loc.T("usage.pill.blockedReason", s.GateReason));
+        else if (s.EffectiveSlots < s.ConfiguredSlots)
+            lines.Add(Loc.T("usage.pill.throttled", s.EffectiveSlots, s.ConfiguredSlots, BucketLabel(s.ThrottleBucket)));
         if (s.IsStale)
         {
             var stamp = s.FetchedAtUtc?.ToLocalTime().ToString("HH:mm") ?? "?";
@@ -106,6 +111,13 @@ public sealed partial class UsagePillViewModel : ViewModelBase
         return lines.Count > 0 ? string.Join(Environment.NewLine, lines) : Loc.T("usage.pill.empty");
     }
 
+    private static string BucketLabel(string? bucket) => bucket switch
+    {
+        "five_hour" => Loc.T("usage.pill.fiveHourLabel"),
+        "seven_day" => Loc.T("usage.pill.sevenDayLabel"),
+        _ => "",
+    };
+
     private static string FormatRemaining(DateTimeOffset resetsAt)
     {
         var remaining = resetsAt - DateTimeOffset.UtcNow;

src/ClaudeDo.Ui/Views/Modals/UsageMonitorModalView.axaml

@@ -52,6 +52,12 @@
                 BorderThickness="1" CornerRadius="6" Padding="12,8">
           <TextBlock Classes="meta" Text="{Binding GateBandText}"/>
         </Border>
+        <Border IsVisible="{Binding IsThrottled}"
+                Background="{DynamicResource ReviewTintBrush}"
+                BorderBrush="{DynamicResource StatusReviewBrush}"
+                BorderThickness="1" CornerRadius="6" Padding="12,8">
+          <TextBlock Classes="meta" Text="{Binding ThrottleBandText}"/>
+        </Border>
       </StackPanel>
 
       <!-- Gauges -->

src/ClaudeDo.Worker/CLAUDE.md

@@ -21,7 +21,7 @@ Worker/
   Report/       — ClaudeHistoryReader, WeekReportPromptBuilder, WeekReportService; interfaces in Report/Interfaces/
   Prime/        — daily-prep ("Prime Claude"): PrimeScheduler (BackgroundService), PrimeRunner (runs the daily prep), DailyPrepPrompt (fixed prompt + CLI args + LogPath() helper), NextDueCalculator, PrimeScheduleSignal; interfaces in Prime/Interfaces/ (IPrimeRunner, IPrimeClock, IPrimeScheduleSignal, IPrimeBroadcaster)
   Online/       — optional Online Inbox sync: OnlineInboxConfig (config record), Dtos (RemoteList/RemoteTask/MirrorTask), IOnlineInboxApi, OnlineInboxApiClient (typed HttpClient, bearer auth, HTTPS guard), OnlineTokenStore (DPAPI refresh-token store, Windows-only), StaticTokenAuthProvider (default/test IOnlineAuthProvider), ZitadelAuthProvider (OIDC discovery + refresh-token flow), OnlineSyncService (BackgroundService: reconcile loop), OnlineBacklog (Idle-backlog filter/query); interface in Online/Interfaces/ (IOnlineAuthProvider)
-  Usage/        — OAuth usage monitor: UsageModels (UsageBucket/UsageLimitRow/UsageSnapshot), ClaudeOAuthUsageClient (reads the access token Claude Code keeps fresh at `~/.claude/.credentials.json`, calls `GET https://api.anthropic.com/api/oauth/usage`; defensive parsing — missing/null buckets → null, missing `limits` → empty list; never logs the token), UsageState (threadsafe singleton; a failed poll never overwrites the last good snapshot, only sets `LastError`), UsageMonitorService (BackgroundService, polls on `usage_poll_interval_seconds`, one poll at startup, logs a failure at most once per distinct error message, broadcasts `HubBroadcaster.UsageUpdated` after every tick via `UsageSnapshotBuilder`), UsageSnapshotBuilder (builds the Hub-facing `UsageSnapshotDto` from `UsageState` + `IUsageGate` + `AppSettings` thresholds — the one place `WorkerHub.GetUsageSnapshot` and `UsageMonitorService` share the stale/threshold/gate logic), TranscriptUsageReader (aggregates Claude Code transcript token usage from `~/.claude/projects/**/*.jsonl` by date/model/scope (ClaudeDo vs Other), deduped by requestId, with a per-file length+mtime cache; `<synthetic>`-model lines are skipped everywhere, not real API calls; also exposes `ReadSessionTotalsAsync(sessionId)` — cumulative raw input/output/cache-read/cache-write totals for one session, located by `{sessionId}.jsonl`, used by `TaskRunner` to populate `task_runs`' per-run token fields), UsageGate (reads `UsageState` + `AppSettings.UsageGateFiveHourPct`/`UsageGateSevenDayPct`, returns a `UsageGateDecision(IsBlocked, Reason)`; `Utilization` from `UsageBucket` is already a 0–100 percent, compared directly against the threshold with `>=`; threshold `0` = that bucket never gates; fail-open — no snapshot yet, a failed last poll, or a settings-read error all resolve to not-blocked); interfaces in Usage/Interfaces/ (IUsageClient, ITranscriptUsageReader, IUsageGate)
+  Usage/        — OAuth usage monitor: UsageModels (UsageBucket/UsageLimitRow/UsageSnapshot), ClaudeOAuthUsageClient (reads the access token Claude Code keeps fresh at `~/.claude/.credentials.json`, calls `GET https://api.anthropic.com/api/oauth/usage`; defensive parsing — missing/null buckets → null, missing `limits` → empty list; never logs the token), UsageState (threadsafe singleton; a failed poll never overwrites the last good snapshot, only sets `LastError`), UsageMonitorService (BackgroundService, polls on `usage_poll_interval_seconds`, one poll at startup, logs a failure at most once per distinct error message, broadcasts `HubBroadcaster.UsageUpdated` after every tick via `UsageSnapshotBuilder`), UsageSnapshotBuilder (builds the Hub-facing `UsageSnapshotDto` from `UsageState` + `IUsageGate` + `AppSettings` thresholds — the one place `WorkerHub.GetUsageSnapshot` and `UsageMonitorService` share the stale/threshold/gate logic), TranscriptUsageReader (aggregates Claude Code transcript token usage from `~/.claude/projects/**/*.jsonl` by date/model/scope (ClaudeDo vs Other), deduped by requestId, with a per-file length+mtime cache; `<synthetic>`-model lines are skipped everywhere, not real API calls; also exposes `ReadSessionTotalsAsync(sessionId)` — cumulative raw input/output/cache-read/cache-write totals for one session, located by `{sessionId}.jsonl`, used by `TaskRunner` to populate `task_runs`' per-run token fields), UsageGate (reads `UsageState` + `AppSettings.UsageGateFiveHourPct`/`UsageGateSevenDayPct`, returns a `UsageGateDecision(IsBlocked, Reason)`; `Utilization` from `UsageBucket` is already a 0–100 percent, compared directly against the threshold with `>=`; threshold `0` = that bucket never gates; fail-open — no snapshot yet, a failed last poll, or a settings-read error all resolve to not-blocked), UsageThrottle (pure static `EffectiveSlots(configuredSlots, fiveHourPct, sevenDayPct, softPct, hardPct, gateFiveHourPct, gateSevenDayPct)` — stages parallelism down ahead of the hard gate: whichever bucket is more utilized decides the stage, `0` for a threshold disables that stage, `>= softPct` caps at 2 slots, `>= hardPct` caps at 1, `>= either gate threshold` returns 0 — same 0 as `UsageGate`'s hard block, kept in sync since both read the same gate thresholds); interfaces in Usage/Interfaces/ (IUsageClient, ITranscriptUsageReader, IUsageGate)
 ```
 
 Interfaces (e.g. `IQueueWaker`, `IPrimeClock`, `ITaskStateService`) live in an `Interfaces/` subfolder within their area; the namespace stays the area namespace.
@@ -30,7 +30,7 @@ Interfaces (e.g. `IQueueWaker`, `IPrimeClock`, `ITaskStateService`) live in an `
 
 - **Program.cs** — loads config, inits schema, registers DI, configures SignalR on `/hub`, binds to `127.0.0.1:47821`
 - **TaskStateService** — only component that writes `Status`, `PlanningPhase`, `BlockedByTaskId`. All transitions return a `TransitionResult` (no exceptions on invalid moves). Wakes the queue and broadcasts `TaskUpdated` automatically; advances the planning chain on child terminal transitions.
-- **IQueueWaker / IQueuePicker / QueueService** — waker is a singleton `SemaphoreSlim`; picker performs the atomic `Queued → Running` claim filtered by `BlockedByTaskId IS NULL`, `is_manual = 0` and schedule; QueueService is a thin `BackgroundService` that loops on the waker and dispatches via `TaskRunner`. On each loop tick, after computing `maxParallel`, it also asks `IUsageGate.EvaluateAsync` — if blocked, the slot-fill loop is skipped entirely for that tick (already-running slots are untouched; `RunNow`/`ContinueTask`/interactive/planning/daily-prep all bypass the queue and are unaffected). A blocked↔free transition is logged/broadcast (`WorkerLog`, Warn on block / Info on resume) exactly once per change, not on every tick; the 30 s backstop timer re-evaluates the gate on its own even with no wake signal, so the queue self-recovers once usage drops back under the threshold.
+- **IQueueWaker / IQueuePicker / QueueService** — waker is a singleton `SemaphoreSlim`; picker performs the atomic `Queued → Running` claim filtered by `BlockedByTaskId IS NULL`, `is_manual = 0` and schedule; QueueService is a thin `BackgroundService` that loops on the waker and dispatches via `TaskRunner`. On each loop tick, `GetEffectiveMaxParallelAsync` reads `AppSettings.MaxParallelExecutions` and steps it down via `UsageThrottle.EffectiveSlots` against the current `UsageState` snapshot (a missing/failed snapshot fails open to the configured value — never throttles on a broken poll); a stage change (not every tick) logs once via the standard logger. Separately, it also asks `IUsageGate.EvaluateAsync` — if blocked, the slot-fill loop is skipped entirely for that tick (already-running slots are untouched in either case; `RunNow`/`ContinueTask`/interactive/planning/daily-prep all bypass the queue and are unaffected). A blocked↔free transition is logged/broadcast (`WorkerLog`, Warn on block / Info on resume) exactly once per change, not on every tick; the 30 s backstop timer re-evaluates both the throttle and the gate on its own even with no wake signal, so the queue self-recovers once usage drops back under the threshold.
 - **OverrideSlotService** — owns `RunNow` / `ContinueTask`; goes through `TaskStateService.StartRunningAsync` (caller-driven, serialized by slot lock).
 - **StaleTaskRecovery** — startup-only service; calls `TaskStateService.RecoverStaleRunningAsync` to flip orphaned `Running` rows to `Failed`.
 - **External/*** — always-on MCP tools for general Claude sessions, scoped to *starting* and *observing* sessions (no worktree/merge, multi-turn, planning, or app-settings writes). Auth via optional `X-ClaudeDo-Key` header. Registered explicitly in `Program.cs`'s external app via `.WithTools<T>()`. Every optional/filter parameter across these tools must carry a C# default value (e.g. `string? status = null`) — the MCP schema only marks a parameter optional when it has one; nullability alone doesn't do it (`ExternalMcpToolSchemaTests` guards this by reflection). `ExternalMcpExceptionFilter.Wrap` is registered as a call-tool filter so `InvalidOperationException`/`ArgumentException` messages survive as `McpException` — otherwise the SDK's own catch-all replaces any non-`McpException` with a generic "An error occurred invoking 'X'." **No external tool returns bare `Task` or a nullable payload directly** — an MCP client can't tell an empty/omitted response apart from a dropped one. Write tools return a small confirmation record (`{ ok/deleted/removed/reset/started: true, <id>, ... }`, e.g. `DeleteListResult`, `RunTaskNowResult`, `ResetFailedTaskResult`, `RemoveAttachmentResult`; `SetListConfigResult`/`SetTaskConfigResult` additionally echo the resulting config so the caller can see which fields were set vs. cleared to null); read tools that may have nothing to return use an explicit `Found`/`Available` flag alongside the nullable payload (`TaskConfigResult`, pre-existing `BatchGetTaskResult`, `TaskLogResult`) instead of returning null outright. Organized by concern:
@@ -79,6 +79,18 @@ recovery is just the queue's 30s backstop timer re-evaluating the gate on its ow
 drops back under the threshold. See `Usage/` in the folder layout above for the component
 breakdown.
 
+Ahead of that hard gate, `UsageThrottle` steps the queue's effective parallelism down in two
+stages (thresholds `usage_throttle_soft_pct`/`usage_throttle_hard_pct`, defaults 50/65):
+whichever of 5h/7d is more utilized decides the stage — below soft = full configured
+`max_parallel_executions`, at/above soft = capped to 2 slots, at/above hard = capped to 1,
+at/above either gate threshold = 0 (the pre-existing hard pause, unchanged). Only *new* slot
+fills are affected; a run already occupying a slot when the stage tightens keeps running to
+completion. Same fail-open policy as the gate — no snapshot yet means no throttling, full
+configured parallelism. The effective stage (configured vs. effective slots, decisive bucket)
+rides along on `UsageSnapshotDto`/`GetUsageSnapshot` for UI display (`UsagePillViewModel`
+tooltip, `UsageMonitorModalViewModel`'s throttle band) — it does not change what the gate
+itself gates on.
+
 ## Status Model
 
 `TaskEntity` carries three orthogonal fields. Lifecycle, planning hierarchy, and chain blocking are no longer conflated.

src/ClaudeDo.Worker/Hub/WorkerHub.cs

@@ -129,7 +129,10 @@ public record UsageSnapshotDto(
     string? GateReason,
     DateTime? FetchedAtUtc,
     bool IsStale,
-    string? LastError);
+    string? LastError,
+    int ConfiguredSlots,
+    int EffectiveSlots,
+    string? ThrottleBucket);
 
 public record ModelUsageRowDto(
     DateOnly Date,

src/ClaudeDo.Worker/Queue/QueueService.cs

@@ -30,6 +30,7 @@ public sealed class QueueService : BackgroundService
     private readonly object _lock = new();
     private readonly Dictionary<string, QueueSlotState> _queueSlots = new();
     private bool _usageGateBlocked;
+    private int? _lastEffectiveSlots;
 
     public QueueService(
         IDbContextFactory<ClaudeDoDbContext> dbFactory,
@@ -124,7 +125,7 @@ public sealed class QueueService : BackgroundService
 
                 await Task.WhenAny(wakeTask, timerTask);
 
-                var maxParallel = await GetMaxParallelAsync(stoppingToken);
+                var maxParallel = await GetEffectiveMaxParallelAsync(stoppingToken);
 
                 var gateDecision = await _usageGate.EvaluateAsync(stoppingToken);
                 await ReportUsageGateTransitionAsync(gateDecision);
@@ -198,19 +199,64 @@ public sealed class QueueService : BackgroundService
         }
     }
 
-    private async Task<int> GetMaxParallelAsync(CancellationToken ct)
+    /// <summary>
+    /// Configured parallelism, stepped down by <see cref="UsageThrottle"/> ahead of the hard usage
+    /// gate. A missing snapshot (poll hasn't landed / endpoint unreachable) fails open to the
+    /// configured value — a broken usage poll must never stall the queue.
+    /// </summary>
+    private async Task<int> GetEffectiveMaxParallelAsync(CancellationToken ct)
     {
+        int configured;
+        int softPct, hardPct, gateFivePct, gateSevenPct;
         try
         {
             using var context = _dbFactory.CreateDbContext();
             var settings = await new AppSettingsRepository(context).GetAsync(ct);
-            return Math.Max(1, settings.MaxParallelExecutions);
+            configured = Math.Max(1, settings.MaxParallelExecutions);
+            softPct = settings.UsageThrottleSoftPct;
+            hardPct = settings.UsageThrottleHardPct;
+            gateFivePct = settings.UsageGateFiveHourPct;
+            gateSevenPct = settings.UsageGateSevenDayPct;
         }
         catch (Exception ex)
         {
             _logger.LogWarning(ex, "Failed to read max parallel executions; defaulting to 1");
             return 1;
         }
+
+        var snapshot = _usageState.Snapshot;
+        if (snapshot is null || _usageState.LastError is not null)
+        {
+            _lastEffectiveSlots = configured;
+            return configured;
+        }
+
+        var effective = UsageThrottle.EffectiveSlots(
+            configured, snapshot.FiveHour?.Utilization, snapshot.SevenDay?.Utilization,
+            softPct, hardPct, gateFivePct, gateSevenPct);
+
+        ReportThrottleTransition(configured, effective, snapshot);
+        return effective;
+    }
+
+    private void ReportThrottleTransition(int configured, int effective, UsageSnapshot snapshot)
+    {
+        if (_lastEffectiveSlots == effective) return;
+        var previous = _lastEffectiveSlots;
+        _lastEffectiveSlots = effective;
+
+        if (previous is null && effective == configured) return; // baseline, nothing to report
+
+        if (effective < configured)
+        {
+            _logger.LogInformation(
+                "QueueService: usage throttle stepped to {Effective}/{Configured} slots (5h={FiveHour}%, 7d={SevenDay}%)",
+                effective, configured, snapshot.FiveHour?.Utilization, snapshot.SevenDay?.Utilization);
+        }
+        else
+        {
+            _logger.LogInformation("QueueService: usage throttle cleared, back to {Configured} slots", configured);
+        }
     }
 
     private async Task RunInSlotAsync(string taskId, CancellationToken ct)

src/ClaudeDo.Worker/Usage/UsageSnapshotBuilder.cs

@@ -46,6 +46,17 @@ public sealed class UsageSnapshotBuilder
             .Select(l => new UsageLimitDto(l.Kind, l.Group, l.Percent, l.Severity, l.ResetsAt, l.ScopeModelDisplayName, l.IsActive))
             .ToList();
 
+        var configuredSlots = Math.Max(1, settings.MaxParallelExecutions);
+        var effectiveSlots = snapshot is null || lastError is not null
+            ? configuredSlots
+            : UsageThrottle.EffectiveSlots(
+                configuredSlots, snapshot.FiveHour?.Utilization, snapshot.SevenDay?.Utilization,
+                settings.UsageThrottleSoftPct, settings.UsageThrottleHardPct,
+                settings.UsageGateFiveHourPct, settings.UsageGateSevenDayPct);
+        var throttleBucket = effectiveSlots < configuredSlots
+            ? DecisiveBucket(snapshot?.FiveHour?.Utilization, snapshot?.SevenDay?.Utilization)
+            : null;
+
         return new UsageSnapshotDto(
             snapshot?.FiveHour?.Utilization,
             snapshot?.FiveHour?.ResetsAt,
@@ -58,6 +69,15 @@ public sealed class UsageSnapshotBuilder
             decision.Reason,
             snapshot?.FetchedAtUtc,
             isStale,
-            lastError);
+            lastError,
+            configuredSlots,
+            effectiveSlots,
+            throttleBucket);
+    }
+
+    private static string? DecisiveBucket(double? fiveHourPct, double? sevenDayPct)
+    {
+        if (fiveHourPct is null && sevenDayPct is null) return null;
+        return (fiveHourPct ?? 0) >= (sevenDayPct ?? 0) ? "five_hour" : "seven_day";
     }
 }

src/ClaudeDo.Worker/Usage/UsageThrottle.cs

@@ -0,0 +1,38 @@
+namespace ClaudeDo.Worker.Usage;
+
+/// <summary>
+/// Pure staged throttle sitting ahead of <see cref="UsageGate"/>'s hard pause: as the 5h/7d usage
+/// window fills up, the queue's effective parallelism steps down before it hits zero, instead of
+/// running at full tilt right up to the gate threshold. Whichever of the two buckets is more
+/// utilized decides the stage. A missing bucket (null) is treated as 0% for that bucket only —
+/// callers with no snapshot at all should skip this and use <paramref name="configuredSlots"/>
+/// directly (fail-open), same policy as <see cref="UsageGate"/>.
+/// </summary>
+public static class UsageThrottle
+{
+    public static int EffectiveSlots(
+        int configuredSlots,
+        double? fiveHourPct,
+        double? sevenDayPct,
+        int softPct,
+        int hardPct,
+        int gateFiveHourPct,
+        int gateSevenDayPct)
+    {
+        var slots = Math.Max(1, configuredSlots);
+
+        if (gateFiveHourPct > 0 && fiveHourPct is { } five && five >= gateFiveHourPct)
+            return 0;
+        if (gateSevenDayPct > 0 && sevenDayPct is { } seven && seven >= gateSevenDayPct)
+            return 0;
+
+        var worst = Math.Max(fiveHourPct ?? 0, sevenDayPct ?? 0);
+
+        if (hardPct > 0 && worst >= hardPct)
+            return Math.Min(slots, 1);
+        if (softPct > 0 && worst >= softPct)
+            return Math.Min(slots, 2);
+
+        return slots;
+    }
+}