From 8c8a59a597bf459024e969e5ede67d9a5e0cea52 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sat, 11 Jul 2026 14:32:59 -0500
Subject: [PATCH 1/9] fix: support Discord DM reminders (#1609)

---
 docs/integrations/discord-channel.md          | 15 ++-
 .../.system/files/netclaw-operations/SKILL.md |  2 +-
 .../references/scheduling.md                  |  4 +
 .../DiscordReminderTargetResolverTests.cs     | 79 ++++++++++++---
 .../Reminders/SetReminderToolTests.cs         | 95 +++++++++++++++++--
 .../Reminders/SetReminderTool.cs              |  9 +-
 .../DiscordReminderTargetResolver.cs          | 89 +++++++++++++----
 ...hannelIntegrationRegistrationExtensions.cs |  2 +-
 .../Configuration/RemoteChatChannelBuilder.cs | 11 +++
 9 files changed, 251 insertions(+), 55 deletions(-)

diff --git a/docs/integrations/discord-channel.md b/docs/integrations/discord-channel.md
index 54aaebc90..9e2a2fef2 100644
--- a/docs/integrations/discord-channel.md
+++ b/docs/integrations/discord-channel.md
@@ -118,9 +118,20 @@ Discord channel target resolution accepts canonical channel forms:
 - `<#123...>` (channel mention)
 - `channel:123...` (explicit channel ID)
 
+Discord direct-message target resolution accepts explicit user forms:
+
+- `<@123...>` or `<@!123...>` (user mention)
+- `dm:123...` or `@123...` (explicit user ID)
+
+Bare Discord snowflakes are rejected because channel IDs and user IDs have the
+same shape. Use `channel:<channelId>` for channel delivery or `dm:<userId>` for
+direct-message delivery.
+
 Reminder channel delivery maps to the generic `send_channel_message` tool with
-`channel_key = "discord"` and a resolved destination object. Discord proactive
-DM output is not supported yet.
+`channel_key = "discord"` and a resolved destination object. Channel targets use
+`destination.kind = "destination"`; user targets use
+`destination.kind = "direct_message"` and are still gated by
+`AllowDirectMessages` and `AllowedUserIds` at send time.
 
 ## Runtime behavior and troubleshooting
 
diff --git a/feeds/skills/.system/files/netclaw-operations/SKILL.md b/feeds/skills/.system/files/netclaw-operations/SKILL.md
index a514dbd60..4980ff49e 100644
--- a/feeds/skills/.system/files/netclaw-operations/SKILL.md
+++ b/feeds/skills/.system/files/netclaw-operations/SKILL.md
@@ -3,7 +3,7 @@ name: netclaw-operations
 description: "REQUIRED when the user asks about scheduling, reminders, cron jobs, timers, background jobs, diagnostics, troubleshooting, MCP tools, daemon health, identity updates, or Netclaw capabilities and self-maintenance."
 metadata:
   author: netclaw
-  version: "2.24.0"
+  version: "2.24.1"
 ---
 
 # Netclaw Operations
diff --git a/feeds/skills/.system/files/netclaw-operations/references/scheduling.md b/feeds/skills/.system/files/netclaw-operations/references/scheduling.md
index 097c95d05..cf65fd583 100644
--- a/feeds/skills/.system/files/netclaw-operations/references/scheduling.md
+++ b/feeds/skills/.system/files/netclaw-operations/references/scheduling.md
@@ -33,6 +33,10 @@ Rules:
   conversational follow-ups in Slack/TUI/SignalR sessions.
 - `channel` requires both transport + address and resolves names/handles to
   canonical IDs at set time; unresolved targets fail loud.
+- Discord reminder targets must be explicit because channel IDs and user IDs are
+  both snowflakes: use `channel:<channelId>` or `<#channelId>` for channel posts,
+  and `dm:<userId>`, `@<userId>`, or `<@userId>` for DMs. Do not pass a bare
+  Discord ID.
 - `none` runs silently (history still records execution).
 - `expires_in` is not valid for `once` reminders; omit it for one-shot schedules.
 - For recurring reminders that are permanently complete (PR merged, deploy done,
diff --git a/src/Netclaw.Actors.Tests/Channels/DiscordReminderTargetResolverTests.cs b/src/Netclaw.Actors.Tests/Channels/DiscordReminderTargetResolverTests.cs
index b2c0bdc9b..a14d88849 100644
--- a/src/Netclaw.Actors.Tests/Channels/DiscordReminderTargetResolverTests.cs
+++ b/src/Netclaw.Actors.Tests/Channels/DiscordReminderTargetResolverTests.cs
@@ -11,30 +11,49 @@ namespace Netclaw.Actors.Tests.Channels;
 
 public sealed class DiscordReminderTargetResolverTests
 {
-    private readonly DiscordReminderTargetResolver _resolver = new();
+    private const string ChannelId = "129847561203948576";
+    private const string UserId = "130111223344556677";
+
+    private readonly DiscordReminderTargetResolver _resolver = new(new DiscordChannelOptions
+    {
+        AllowDirectMessages = true,
+        AllowedChannelIds = [ChannelId],
+        AllowedUserIds = [UserId]
+    });
 
     [Fact]
     public async Task Resolves_channel_mention_to_canonical_channel_id()
     {
-        var result = await _resolver.ResolveAsync("<#129847561203948576>", TestContext.Current.CancellationToken);
+        var result = await _resolver.ResolveAsync($"<#{ChannelId}>", TestContext.Current.CancellationToken);
 
         Assert.True(result.Success);
         Assert.Equal(ReminderTargetKind.Channel, result.Kind);
-        Assert.Equal("129847561203948576", result.ResolvedId);
+        Assert.Equal(ChannelId, result.ResolvedId);
         Assert.Null(result.ErrorMessage);
     }
 
     [Fact]
     public async Task Resolves_explicit_channel_prefix_to_canonical_channel_id()
     {
-        var result = await _resolver.ResolveAsync("channel:129847561203948576", TestContext.Current.CancellationToken);
+        var result = await _resolver.ResolveAsync($"channel:{ChannelId}", TestContext.Current.CancellationToken);
 
         Assert.True(result.Success);
         Assert.Equal(ReminderTargetKind.Channel, result.Kind);
-        Assert.Equal("129847561203948576", result.ResolvedId);
+        Assert.Equal(ChannelId, result.ResolvedId);
         Assert.Null(result.ErrorMessage);
     }
 
+    [Fact]
+    public async Task Rejects_channel_targets_outside_allowed_channels()
+    {
+        var result = await _resolver.ResolveAsync("channel:129847561203948577", TestContext.Current.CancellationToken);
+
+        Assert.False(result.Success);
+        Assert.Equal(ReminderTargetKind.Unknown, result.Kind);
+        Assert.Null(result.ResolvedId);
+        Assert.Contains("allowed channels", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
+    }
+
     [Fact]
     public async Task Rejects_bare_snowflakes_because_they_are_ambiguous()
     {
@@ -50,26 +69,60 @@ public async Task Rejects_bare_snowflakes_because_they_are_ambiguous()
     [InlineData("@129847561203948576")]
     [InlineData("<@129847561203948576>")]
     [InlineData("<@!129847561203948576>")]
-    public async Task Rejects_user_targets_while_discord_reminders_are_channel_only(string input)
+    [InlineData("dm:129847561203948576")]
+    public async Task Resolves_explicit_user_targets_to_canonical_user_id(string input)
+    {
+        var resolver = new DiscordReminderTargetResolver(new DiscordChannelOptions
+        {
+            AllowDirectMessages = true,
+            AllowedUserIds = ["129847561203948576"]
+        });
+
+        var result = await resolver.ResolveAsync(input, TestContext.Current.CancellationToken);
+
+        Assert.True(result.Success);
+        Assert.Equal(ReminderTargetKind.User, result.Kind);
+        Assert.Equal("129847561203948576", result.ResolvedId);
+        Assert.Null(result.ErrorMessage);
+    }
+
+    [Fact]
+    public async Task Rejects_user_targets_when_direct_messages_are_disabled()
+    {
+        var resolver = new DiscordReminderTargetResolver(new DiscordChannelOptions
+        {
+            AllowDirectMessages = false,
+            AllowedUserIds = [UserId]
+        });
+
+        var result = await resolver.ResolveAsync($"dm:{UserId}", TestContext.Current.CancellationToken);
+
+        Assert.False(result.Success);
+        Assert.Equal(ReminderTargetKind.Unknown, result.Kind);
+        Assert.Null(result.ResolvedId);
+        Assert.Contains("disabled", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task Rejects_user_targets_outside_allowed_users()
     {
-        var result = await _resolver.ResolveAsync(input, TestContext.Current.CancellationToken);
+        var result = await _resolver.ResolveAsync("dm:130111223344556678", TestContext.Current.CancellationToken);
 
         Assert.False(result.Success);
         Assert.Equal(ReminderTargetKind.Unknown, result.Kind);
         Assert.Null(result.ResolvedId);
-        Assert.Contains("channel", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
-        Assert.Contains("not supported", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("allowed users", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
     }
 
     [Fact]
-    public async Task Rejects_dm_channel_prefix_while_discord_reminders_are_channel_only()
+    public async Task Rejects_invalid_direct_message_target()
     {
-        var result = await _resolver.ResolveAsync("dm:130111223344556677", TestContext.Current.CancellationToken);
+        var result = await _resolver.ResolveAsync("dm:not-a-user-id", TestContext.Current.CancellationToken);
 
         Assert.False(result.Success);
         Assert.Equal(ReminderTargetKind.Unknown, result.Kind);
         Assert.Null(result.ResolvedId);
-        Assert.Contains("DM", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("direct-message", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
     }
 
     [Fact]
@@ -80,6 +133,6 @@ public async Task Rejects_non_canonical_discord_targets()
         Assert.False(result.Success);
         Assert.Equal(ReminderTargetKind.Unknown, result.Kind);
         Assert.Null(result.ResolvedId);
-        Assert.Contains("channel:<channelId>", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("user target", result.ErrorMessage, StringComparison.OrdinalIgnoreCase);
     }
 }
diff --git a/src/Netclaw.Actors.Tests/Reminders/SetReminderToolTests.cs b/src/Netclaw.Actors.Tests/Reminders/SetReminderToolTests.cs
index 14123f8ad..87af6b1a5 100644
--- a/src/Netclaw.Actors.Tests/Reminders/SetReminderToolTests.cs
+++ b/src/Netclaw.Actors.Tests/Reminders/SetReminderToolTests.cs
@@ -12,6 +12,7 @@
 using Netclaw.Actors.Channels;
 using Netclaw.Actors.Reminders;
 using Netclaw.Actors.Tests.Hosting;
+using Netclaw.Channels.Discord;
 using Netclaw.Configuration;
 using Netclaw.Tools;
 using Xunit;
@@ -810,7 +811,7 @@ public async Task Mode_B_session_reentry_skips_resolver()
     }
 
     [Fact]
-    public async Task Resolves_user_target_to_dm_notify_instructions()
+    public async Task Resolves_user_target_to_direct_message_delivery_target()
     {
         var probe = CreateTestProbe();
         var resolver = new TestResolver
@@ -839,6 +840,10 @@ public async Task Resolves_user_target_to_dm_notify_instructions()
         var cmd = await probe.ExpectMsgAsync<SaveReminderCommand>(TimeSpan.FromSeconds(5), cancellationToken: TestContext.Current.CancellationToken);
         Assert.Equal(DeliveryKind.Channel, cmd.Definition.Delivery.Kind);
         Assert.Equal("U0456XYZ", cmd.Definition.Delivery.Address);
+        Assert.NotNull(cmd.Definition.Delivery.Target);
+        Assert.Equal("slack", cmd.Definition.Delivery.Target!.ChannelKey);
+        Assert.Equal("direct_message", cmd.Definition.Delivery.Target.DestinationKind);
+        Assert.Equal("U0456XYZ", cmd.Definition.Delivery.Target.DestinationId);
         Assert.Equal(1, resolver.CallCount);
 
         probe.Reply(new ReminderSavedResponse(
@@ -851,7 +856,7 @@ public async Task Resolves_user_target_to_dm_notify_instructions()
     }
 
     [Fact]
-    public async Task Rejects_discord_user_target_with_discord_transport()
+    public async Task Resolves_discord_user_target_to_direct_message_delivery_target()
     {
         var probe = CreateTestProbe();
         var resolver = new TestResolver
@@ -863,22 +868,94 @@ public async Task Rejects_discord_user_target_with_discord_transport()
         };
         var tool = new SetReminderTool(probe, _timeProvider, new SchedulingConfig(), [resolver]);
 
+        var execution = Task.Run(async () =>
+        {
+            return await tool.ExecuteAsync(new Dictionary<string, object?>
+            {
+                ["Id"] = "discord-user-target",
+                ["Name"] = "discord-user-target",
+                ["Prompt"] = "Send results",
+                ["ScheduleType"] = "once",
+                ["Schedule"] = "15m",
+                ["DeliveryKind"] = "channel",
+                ["DeliveryTransport"] = "discord",
+                ["DeliveryAddress"] = "<@129847561203948576>"
+            }, TestContext.Current.CancellationToken);
+        }, TestContext.Current.CancellationToken);
+
+        var cmd = await probe.ExpectMsgAsync<SaveReminderCommand>(TimeSpan.FromSeconds(5), cancellationToken: TestContext.Current.CancellationToken);
+        Assert.Equal(DeliveryKind.Channel, cmd.Definition.Delivery.Kind);
+        Assert.Equal("discord", cmd.Definition.Delivery.Transport);
+        Assert.Equal("129847561203948576", cmd.Definition.Delivery.Address);
+        Assert.NotNull(cmd.Definition.Delivery.Target);
+        Assert.Equal("discord", cmd.Definition.Delivery.Target!.ChannelKey);
+        Assert.Equal("direct_message", cmd.Definition.Delivery.Target.DestinationKind);
+        Assert.Equal("129847561203948576", cmd.Definition.Delivery.Target.DestinationId);
+        Assert.Equal("129847561203948576", cmd.Definition.Delivery.Target.DestinationDisplayName);
+        Assert.Equal(1, resolver.CallCount);
+
+        probe.Reply(new ReminderSavedResponse(
+            cmd.Definition.Id,
+            cmd.Definition.Title,
+            Success: true,
+            NextFire: _timeProvider.GetUtcNow().AddMinutes(15)));
+
+        var result = await execution;
+        Assert.StartsWith("Reminder 'discord-user-target' scheduled.", result);
+    }
+
+    [Fact]
+    public async Task Rejects_discord_direct_message_reminder_when_direct_messages_are_disabled()
+    {
+        var probe = CreateTestProbe();
+        var resolver = new DiscordReminderTargetResolver(new DiscordChannelOptions
+        {
+            AllowDirectMessages = false
+        });
+        var tool = new SetReminderTool(probe, _timeProvider, new SchedulingConfig(), [resolver]);
+
         var result = await tool.ExecuteAsync(new Dictionary<string, object?>
         {
-            ["Id"] = "discord-user-target",
-            ["Name"] = "discord-user-target",
+            ["Id"] = "discord-dm-disabled",
+            ["Name"] = "discord-dm-disabled",
             ["Prompt"] = "Send results",
             ["ScheduleType"] = "once",
             ["Schedule"] = "15m",
             ["DeliveryKind"] = "channel",
             ["DeliveryTransport"] = "discord",
-            ["DeliveryAddress"] = "<@129847561203948576>"
+            ["DeliveryAddress"] = "dm:129847561203948576"
         }, TestContext.Current.CancellationToken);
 
-        Assert.StartsWith("Error:", result);
-        Assert.Contains("guild text-channel targets only", result, StringComparison.OrdinalIgnoreCase);
-        Assert.Contains("channel:<channelId>", result, StringComparison.OrdinalIgnoreCase);
-        Assert.Equal(1, resolver.CallCount);
+        Assert.StartsWith("Error: Could not resolve delivery_address", result);
+        Assert.Contains("direct messages are disabled", result, StringComparison.OrdinalIgnoreCase);
+        await probe.ExpectNoMsgAsync(TimeSpan.FromMilliseconds(100), TestContext.Current.CancellationToken);
+    }
+
+    [Fact]
+    public async Task Rejects_discord_direct_message_reminder_when_user_is_not_allowlisted()
+    {
+        var probe = CreateTestProbe();
+        var resolver = new DiscordReminderTargetResolver(new DiscordChannelOptions
+        {
+            AllowDirectMessages = true,
+            AllowedUserIds = ["130111223344556677"]
+        });
+        var tool = new SetReminderTool(probe, _timeProvider, new SchedulingConfig(), [resolver]);
+
+        var result = await tool.ExecuteAsync(new Dictionary<string, object?>
+        {
+            ["Id"] = "discord-dm-disallowed",
+            ["Name"] = "discord-dm-disallowed",
+            ["Prompt"] = "Send results",
+            ["ScheduleType"] = "once",
+            ["Schedule"] = "15m",
+            ["DeliveryKind"] = "channel",
+            ["DeliveryTransport"] = "discord",
+            ["DeliveryAddress"] = "dm:129847561203948576"
+        }, TestContext.Current.CancellationToken);
+
+        Assert.StartsWith("Error: Could not resolve delivery_address", result);
+        Assert.Contains("allowed users", result, StringComparison.OrdinalIgnoreCase);
         await probe.ExpectNoMsgAsync(TimeSpan.FromMilliseconds(100), TestContext.Current.CancellationToken);
     }
 
diff --git a/src/Netclaw.Actors/Reminders/SetReminderTool.cs b/src/Netclaw.Actors/Reminders/SetReminderTool.cs
index 1b199f0e3..5c1866b9b 100644
--- a/src/Netclaw.Actors/Reminders/SetReminderTool.cs
+++ b/src/Netclaw.Actors/Reminders/SetReminderTool.cs
@@ -174,7 +174,7 @@ protected override async Task<string> ExecuteAsync(Params args, ToolExecutionCon
                 {
                     var detail = resolution.ErrorMessage ?? "unresolvable target";
                     var hint = string.Equals(transport, "discord", StringComparison.OrdinalIgnoreCase)
-                        ? "Use channel:<channelId> or <#channelId>."
+                        ? "Use channel:<channelId>, <#channelId>, dm:<userId>, or <@userId>."
                         : "Use #channel, @user, or a valid channel ID.";
                     return $"Error: Could not resolve delivery_address '{rawDeliveryAddress}': {detail}. {hint}";
                 }
@@ -182,13 +182,6 @@ protected override async Task<string> ExecuteAsync(Params args, ToolExecutionCon
                 if (string.IsNullOrWhiteSpace(resolution.ResolvedId))
                     return $"Error: Could not resolve delivery_address '{rawDeliveryAddress}': resolver returned an empty canonical target ID.";
 
-                if (string.Equals(transport, "discord", StringComparison.OrdinalIgnoreCase)
-                    && resolution.Kind is not ReminderTargetKind.Channel)
-                {
-                    return "Error: Discord channel delivery currently supports guild text-channel targets only. "
-                           + "Use channel:<channelId> or <#channelId>; user and DM targets are not supported yet.";
-                }
-
                 delivery = new ReminderDelivery
                 {
                     Kind = DeliveryKind.Channel,
diff --git a/src/Netclaw.Channels.Discord/DiscordReminderTargetResolver.cs b/src/Netclaw.Channels.Discord/DiscordReminderTargetResolver.cs
index 99dd2b776..d2394bb9b 100644
--- a/src/Netclaw.Channels.Discord/DiscordReminderTargetResolver.cs
+++ b/src/Netclaw.Channels.Discord/DiscordReminderTargetResolver.cs
@@ -9,14 +9,14 @@
 namespace Netclaw.Channels.Discord;
 
 /// <summary>
-/// Resolves Discord reminder targets to canonical guild text-channel IDs.
-/// Current reminder delivery is channel-only: proactive DM delivery is deferred
-/// until Discord gains a session model that can preserve thread context.
+/// Resolves Discord reminder targets to canonical guild text-channel or user IDs.
 /// Supported inputs:
 /// - channel mention: &lt;#123...&gt;
 /// - explicit channel ID: channel:123...
+/// - user mention: &lt;@123...&gt; or &lt;@!123...&gt;
+/// - explicit user ID: dm:123... or @123...
 /// </summary>
-public sealed class DiscordReminderTargetResolver : IReminderTargetResolver
+public sealed class DiscordReminderTargetResolver(DiscordChannelOptions options) : IReminderTargetResolver
 {
     private static readonly Regex MentionRegex =
         new("^<@!?([0-9]{17,20})>$", RegexOptions.Compiled | RegexOptions.CultureInvariant);
@@ -44,24 +44,22 @@ public Task<ReminderTargetResolution> ResolveAsync(string target, CancellationTo
 
         if (raw.StartsWith("dm:", StringComparison.OrdinalIgnoreCase))
         {
+            var userId = raw[3..].Trim();
+            if (SnowflakeRegex.IsMatch(userId))
+                return Task.FromResult(ResolveUser(userId));
+
             return Task.FromResult(new ReminderTargetResolution(
                 Success: false,
                 ResolvedId: null,
                 Kind: ReminderTargetKind.Unknown,
-                ErrorMessage: "Discord reminder delivery currently supports guild text channels only; DM targets are not supported. Use channel:<channelId> or <#channelId>."));
+                ErrorMessage: "Invalid Discord direct-message target. Use dm:<userId>, @<userId>, or <@userId>."));
         }
 
         if (raw.StartsWith("channel:", StringComparison.OrdinalIgnoreCase))
         {
             var channelId = raw[8..].Trim();
             if (SnowflakeRegex.IsMatch(channelId))
-            {
-                return Task.FromResult(new ReminderTargetResolution(
-                    Success: true,
-                    ResolvedId: channelId,
-                    Kind: ReminderTargetKind.Channel,
-                    ErrorMessage: null));
-            }
+                return Task.FromResult(ResolveChannel(channelId));
 
             return Task.FromResult(new ReminderTargetResolution(
                 Success: false,
@@ -73,11 +71,7 @@ public Task<ReminderTargetResolution> ResolveAsync(string target, CancellationTo
         var channelMention = ChannelMentionRegex.Match(raw);
         if (channelMention.Success)
         {
-            return Task.FromResult(new ReminderTargetResolution(
-                Success: true,
-                ResolvedId: channelMention.Groups[1].Value,
-                Kind: ReminderTargetKind.Channel,
-                ErrorMessage: null));
+            return Task.FromResult(ResolveChannel(channelMention.Groups[1].Value));
         }
 
         if (SnowflakeRegex.IsMatch(raw))
@@ -86,23 +80,76 @@ public Task<ReminderTargetResolution> ResolveAsync(string target, CancellationTo
                 Success: false,
                 ResolvedId: null,
                 Kind: ReminderTargetKind.Unknown,
-                ErrorMessage: "Bare Discord snowflakes are ambiguous. Use channel:<channelId> or <#channelId> for channel delivery."));
+                ErrorMessage: "Bare Discord snowflakes are ambiguous. Use channel:<channelId> or <#channelId> for channel delivery, or dm:<userId> / <@userId> for direct-message delivery."));
         }
 
         var mention = MentionRegex.Match(raw);
-        if (mention.Success || raw.StartsWith("@", StringComparison.Ordinal))
+        if (mention.Success)
         {
+            return Task.FromResult(ResolveUser(mention.Groups[1].Value));
+        }
+
+        if (raw.StartsWith("@", StringComparison.Ordinal))
+        {
+            var userId = raw[1..].Trim();
+            if (SnowflakeRegex.IsMatch(userId))
+                return Task.FromResult(ResolveUser(userId));
+
             return Task.FromResult(new ReminderTargetResolution(
                 Success: false,
                 ResolvedId: null,
                 Kind: ReminderTargetKind.Unknown,
-                ErrorMessage: "Discord reminder delivery currently supports guild text channels only; user/DM targets are not supported. Use channel:<channelId> or <#channelId>."));
+                ErrorMessage: "Invalid Discord user target. Use @<userId>, <@userId>, or dm:<userId>."));
         }
 
         return Task.FromResult(new ReminderTargetResolution(
             Success: false,
             ResolvedId: null,
             Kind: ReminderTargetKind.Unknown,
-            ErrorMessage: $"Could not resolve Discord target '{target}'. Use channel:<channelId> or <#channelId>."));
+            ErrorMessage: $"Could not resolve Discord target '{target}'. Use channel:<channelId>, <#channelId>, dm:<userId>, or <@userId>."));
+    }
+
+    private ReminderTargetResolution ResolveChannel(string channelId)
+    {
+        return DiscordAclPolicy.IsAllowedChannel(new DiscordChannelId(channelId), options, GetDefaultChannelId())
+            ? new ReminderTargetResolution(
+                Success: true,
+                ResolvedId: channelId,
+                Kind: ReminderTargetKind.Channel,
+                ErrorMessage: null)
+            : new ReminderTargetResolution(
+                Success: false,
+                ResolvedId: null,
+                Kind: ReminderTargetKind.Unknown,
+                ErrorMessage: $"Discord channel '{channelId}' is not in the allowed channels list.");
     }
+
+    private ReminderTargetResolution ResolveUser(string userId)
+    {
+        if (!options.AllowDirectMessages)
+        {
+            return new ReminderTargetResolution(
+                Success: false,
+                ResolvedId: null,
+                Kind: ReminderTargetKind.Unknown,
+                ErrorMessage: "Discord direct messages are disabled in configuration.");
+        }
+
+        return DiscordAclPolicy.IsAllowedUser(new DiscordUserId(userId), options)
+            ? new ReminderTargetResolution(
+                Success: true,
+                ResolvedId: userId,
+                Kind: ReminderTargetKind.User,
+                ErrorMessage: null)
+            : new ReminderTargetResolution(
+                Success: false,
+                ResolvedId: null,
+                Kind: ReminderTargetKind.Unknown,
+                ErrorMessage: $"Discord user '{userId}' is not in the allowed users list.");
+    }
+
+    private DiscordChannelId? GetDefaultChannelId()
+        => string.IsNullOrWhiteSpace(options.DefaultChannelId)
+            ? null
+            : new DiscordChannelId(options.DefaultChannelId);
 }
diff --git a/src/Netclaw.Daemon/Configuration/ChannelIntegrationRegistrationExtensions.cs b/src/Netclaw.Daemon/Configuration/ChannelIntegrationRegistrationExtensions.cs
index 1b8f8a530..882ad9bc1 100644
--- a/src/Netclaw.Daemon/Configuration/ChannelIntegrationRegistrationExtensions.cs
+++ b/src/Netclaw.Daemon/Configuration/ChannelIntegrationRegistrationExtensions.cs
@@ -174,7 +174,7 @@ internal static void AddDiscordChannel(IServiceCollection services, IConfigurati
                     paths,
                     logger);
             })
-            .WithReminderResolver<DiscordReminderTargetResolver>()
+            .WithReminderResolver((_, options) => new DiscordReminderTargetResolver(options))
             .WithResolver((sp, options) => new DiscordAddressResolver(
                 sp.GetRequiredService<IDiscordAddressLookupClient>(),
                 options,
diff --git a/src/Netclaw.Daemon/Configuration/RemoteChatChannelBuilder.cs b/src/Netclaw.Daemon/Configuration/RemoteChatChannelBuilder.cs
index 94af668d4..ef10a39ed 100644
--- a/src/Netclaw.Daemon/Configuration/RemoteChatChannelBuilder.cs
+++ b/src/Netclaw.Daemon/Configuration/RemoteChatChannelBuilder.cs
@@ -184,6 +184,17 @@ public RemoteChatChannelBuilder<TChannel, TOptions> WithReminderResolver<TResolv
         return this;
     }
 
+    /// <summary>Registers the channel's reminder target resolver.</summary>
+    public RemoteChatChannelBuilder<TChannel, TOptions> WithReminderResolver<TResolver>(
+        Func<IServiceProvider, TOptions, TResolver> factory)
+        where TResolver : class, IReminderTargetResolver
+    {
+        ArgumentNullException.ThrowIfNull(factory);
+        if (_options.Enabled)
+            _services.AddSingleton<IReminderTargetResolver>(sp => factory(sp, _options));
+        return this;
+    }
+
     /// <summary>
     /// Registers the channel's thread history fetcher, keyed by the channel
     /// key. Keying is load-bearing: an unkeyed registration would make every

From dc2cc733c2ef558cb69df818b1af6fd46fefe8e4 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sat, 11 Jul 2026 15:07:54 -0500
Subject: [PATCH 2/9] Refactor ModelContextProtocol versioning in props file
 (#1614)

Updated ModelContextProtocol package versions to use a variable for versioning.

Signed-off-by: Aaron Stannard <aaron@petabridge.com>
---
 Directory.Packages.props | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 681d538bd..915513305 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -19,6 +19,7 @@
          that trips NU1902 under our TreatWarningsAsErrors policy. -->
     <AspireHostingVersion>13.4.6</AspireHostingVersion>
     <CommunityToolkitAspireVersion>13.4.0</CommunityToolkitAspireVersion>
+    <ModelContextProtocolVersion>1.4.1</ModelContextProtocolVersion>
   </PropertyGroup>
   <!-- App dependencies -->
   <ItemGroup>
@@ -43,8 +44,8 @@
     <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="$(MicrosoftExtensionsAIVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="$(MicrosoftAspNetCoreVersion)" />
     <PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="$(MicrosoftExtensionsAIVersion)" />
-    <PackageVersion Include="ModelContextProtocol.Core" Version="1.4.0" />
-    <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="1.4.0" />
+    <PackageVersion Include="ModelContextProtocol.Core" Version="$(ModelContextProtocolVersion)" />
+    <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="$(ModelContextProtocolVersion)" />
     <PackageVersion Include="Microsoft.AspNetCore.SignalR.Client" Version="$(MicrosoftAspNetCoreVersion)" />
     <PackageVersion Include="Microsoft.AspNetCore.DataProtection" Version="$(MicrosoftAspNetCoreVersion)" />
     <PackageVersion Include="System.Security.Cryptography.Xml" Version="$(MicrosoftAspNetCoreVersion)" />

From 09c63c69816a0b8915501e702b06795b11462ea8 Mon Sep 17 00:00:00 2001
From: "petabridge-netclaw[bot]"
 <289234546+petabridge-netclaw[bot]@users.noreply.github.com>
Date: Sat, 11 Jul 2026 15:40:47 -0500
Subject: [PATCH 3/9] fix: serialize Slack processing status updates (#1556)

Co-authored-by: Aaron Stannard <aaron@petabridge.com>
---
 .../SlackSessionBindingContractTests.cs       | 96 +++++++++++++++++++
 .../SlackThreadBindingActor.cs                | 39 +++++++-
 2 files changed, 130 insertions(+), 5 deletions(-)

diff --git a/src/Netclaw.Actors.Tests/Channels/Contracts/SlackSessionBindingContractTests.cs b/src/Netclaw.Actors.Tests/Channels/Contracts/SlackSessionBindingContractTests.cs
index defc6a63e..7bbcc26ec 100644
--- a/src/Netclaw.Actors.Tests/Channels/Contracts/SlackSessionBindingContractTests.cs
+++ b/src/Netclaw.Actors.Tests/Channels/Contracts/SlackSessionBindingContractTests.cs
@@ -227,6 +227,61 @@ await AwaitAssertAsync(() =>
         }, cancellationToken: ct);
     }
 
+    [Fact]
+    public async Task Processing_state_renders_are_serialized_in_output_order()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var detector = new ConfigurablePromptInjectionDetector(PromptInjectionResult.Safe());
+        var sid = new SessionId("session-slack-processing-ordered");
+        var renderer = new OrderedProcessingRenderer();
+        var registry = TestChannelRegistries.SlackWithProcessingRenderer(renderer);
+        var pipeline = new RecordingSessionPipeline(_ =>
+        [
+            new ProcessingStateOutput(true) { SessionId = sid },
+            new ProcessingStateOutput(false) { SessionId = sid },
+            new TurnCompleted { SessionId = sid, TurnNumber = new TurnNumber(1) }
+        ]);
+
+        CreateActorCore(sid, pipeline, detector, channelRegistry: registry);
+
+        await renderer.FirstStarted.WaitAsync(ct);
+        await AwaitAssertAsync(
+            () => Assert.NotEmpty(_replyClient.Posts),
+            cancellationToken: ct);
+        Assert.False(renderer.SecondStarted.IsCompleted);
+
+        renderer.ReleaseFirst();
+        await renderer.SecondStarted.WaitAsync(ct);
+
+        Assert.Collection(
+            renderer.States,
+            state => Assert.True(state),
+            state => Assert.False(state));
+    }
+
+    [Fact]
+    public async Task Turn_completion_does_not_clear_status_while_session_remains_processing()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var detector = new ConfigurablePromptInjectionDetector(PromptInjectionResult.Safe());
+        var sid = new SessionId("session-slack-processing-buffered-turn");
+        var pipeline = new RecordingSessionPipeline(_ =>
+        [
+            new ProcessingStateOutput(true) { SessionId = sid },
+            new TextOutput("First turn completed; continuing with buffered input.") { SessionId = sid },
+            new TurnCompleted { SessionId = sid, TurnNumber = new TurnNumber(1) }
+        ]);
+
+        CreateActorCore(sid, pipeline, detector);
+
+        await AwaitAssertAsync(() =>
+        {
+            Assert.Contains(_replyClient.Posts, p => p.Text == "First turn completed; continuing with buffered input.");
+            Assert.NotEmpty(_replyClient.Statuses);
+            Assert.All(_replyClient.Statuses, status => Assert.Equal("is thinking...", status.Status));
+        }, cancellationToken: ct);
+    }
+
     [Fact]
     public async Task Inbound_message_refreshes_active_processing_status()
     {
@@ -580,4 +635,45 @@ public ValueTask RenderAsync(
         }
     }
 
+    private sealed class OrderedProcessingRenderer : IChannelOutputRenderer
+    {
+        private readonly object _lock = new();
+        private readonly TaskCompletionSource _firstStarted = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly TaskCompletionSource _releaseFirst = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly TaskCompletionSource _secondStarted = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly List<bool> _states = [];
+
+        public ChannelDescriptorKey Key => ChannelDescriptorKey.FromChannelType(ChannelType.Slack);
+        public Task FirstStarted => _firstStarted.Task;
+        public Task SecondStarted => _secondStarted.Task;
+        public IReadOnlyList<bool> States
+        {
+            get { lock (_lock) return _states.ToList(); }
+        }
+
+        public void ReleaseFirst() => _releaseFirst.TrySetResult();
+
+        public ValueTask RenderAsync(
+            ChannelOutputRenderRequest request,
+            CancellationToken cancellationToken = default)
+        {
+            var state = Assert.IsType<ProcessingStateOutput>(request.Output).IsProcessing;
+            int invocation;
+            lock (_lock)
+            {
+                _states.Add(state);
+                invocation = _states.Count;
+            }
+
+            if (invocation == 1)
+            {
+                _firstStarted.TrySetResult();
+                return new ValueTask(_releaseFirst.Task);
+            }
+
+            _secondStarted.TrySetResult();
+            return ValueTask.CompletedTask;
+        }
+    }
+
 }
diff --git a/src/Netclaw.Channels.Slack/SlackThreadBindingActor.cs b/src/Netclaw.Channels.Slack/SlackThreadBindingActor.cs
index 6a3435edb..b58891f38 100644
--- a/src/Netclaw.Channels.Slack/SlackThreadBindingActor.cs
+++ b/src/Netclaw.Channels.Slack/SlackThreadBindingActor.cs
@@ -62,6 +62,8 @@ internal sealed class SlackThreadBindingActor : ReceivePersistentActor, IWithTim
     private SlackEventTs? _cursorTs;
     private SlackEventTs? _pendingCursorTs;
     private volatile bool _processingIndicatorActive;
+    private readonly object _processingIndicatorRenderLock = new();
+    private Task _processingIndicatorRenderTail = Task.CompletedTask;
 
     // Set when PerformOneShotHydrationAsync fetched a non-empty thread gap but
     // found no authorized trigger to anchor a turn. This is the proactive-thread
@@ -1168,7 +1170,6 @@ private async Task HandleOutputAsync(ThreadOutput threadOutput)
                         cleared => ApplyPendingApprovalPromptCleared(cleared));
                 }
                 _pendingApprovalRequests.Clear();
-
                 break;
         }
     }
@@ -1185,11 +1186,39 @@ private Task RenderProcessingStateAsync(ProcessingStateOutput output)
             ChannelOutputEffectKind.ProcessingIndicator,
             requirement);
 
-        if (output.IsRequired)
-            return RenderProcessingStateRequestAsync(request, isRequired: true);
+        var renderTask = QueueProcessingStateRender(request, output.IsRequired);
+        return output.IsRequired ? renderTask : Task.CompletedTask;
+    }
+
+    private Task QueueProcessingStateRender(ChannelOutputRenderRequest request, bool isRequired)
+    {
+        lock (_processingIndicatorRenderLock)
+        {
+            _processingIndicatorRenderTail = RenderAfterPreviousAsync(
+                _processingIndicatorRenderTail,
+                request,
+                isRequired);
+            return _processingIndicatorRenderTail;
+        }
+    }
+
+    private async Task RenderAfterPreviousAsync(
+        Task previous,
+        ChannelOutputRenderRequest request,
+        bool isRequired)
+    {
+        try
+        {
+            await previous.ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            // A failed required render is reported to its caller. It must not
+            // poison the queue and prevent newer state from reaching Slack.
+            _log.Warning(ex, "Previous required Slack processing indicator render failed; continuing with newer state");
+        }
 
-        _ = RenderProcessingStateRequestAsync(request, isRequired: false);
-        return Task.CompletedTask;
+        await RenderProcessingStateRequestAsync(request, isRequired).ConfigureAwait(false);
     }
 
     private void QueueProcessingIndicatorClearIfActive()

From e31ecdd663e3031cbd6e7628995ad0fc6d4842eb Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sat, 11 Jul 2026 19:04:23 -0500
Subject: [PATCH 4/9] ci: run required checks for merge queue groups (#1617)

---
 .github/workflows/pr_validation.yml | 5 +++++
 .github/workflows/smoke.yml         | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/.github/workflows/pr_validation.yml b/.github/workflows/pr_validation.yml
index f3e7ca2be..926626864 100644
--- a/.github/workflows/pr_validation.yml
+++ b/.github/workflows/pr_validation.yml
@@ -1,6 +1,11 @@
 name: pr_validation
 
 on:
+  # Merge queues test a synthetic merge group rather than the pull request ref.
+  # Required checks must subscribe to this event or queued PRs will never merge.
+  merge_group:
+    types:
+      - checks_requested
   push:
     branches:
       - master
diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
index e7a61b259..5e9062704 100644
--- a/.github/workflows/smoke.yml
+++ b/.github/workflows/smoke.yml
@@ -11,6 +11,11 @@ name: smoke
 # surface via GitHub's built-in Actions notifications.
 
 on:
+  # Merge queues test a synthetic merge group rather than the pull request ref.
+  # Required checks must subscribe to this event or queued PRs will never merge.
+  merge_group:
+    types:
+      - checks_requested
   workflow_dispatch:
   schedule:
     # 07:00 UTC daily — catches external-dependency drift during quiet

From d6c6c28bbe9339834c25db88b7c68b2c828437ad Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 11 Jul 2026 19:07:31 -0500
Subject: [PATCH 5/9] Bump MessagePack from 3.1.7 to 3.1.8 (#1605)

---
updated-dependencies:
- dependency-name: MessagePack
  dependency-version: 3.1.8
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Directory.Packages.props | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 915513305..67d953473 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -97,7 +97,7 @@
          trips NU1903 (GHSA-hv8m-jj95-wg3x, LZ4 decompression AccessViolation).
          Keep this on the patched 3.x line already used by dev until Aspire ships
          a non-vulnerable transitive dependency on its own. -->
-    <PackageVersion Include="MessagePack" Version="3.1.7" />
+    <PackageVersion Include="MessagePack" Version="3.1.8" />
   </ItemGroup>
   <!-- Image normalization (Netclaw.Media). SkiaSharp ships Windows/macOS native
        assets in the base package; Linux needs the explicit headless native asset

From 3f661a83309c33f04edd9601f07ab4695b267a65 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sat, 11 Jul 2026 19:52:20 -0500
Subject: [PATCH 6/9] fix(cli): model set/picker preserve hand-set modalities
 on re-set (#1127) (#1610)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(cli): model set/picker preserve hand-set modalities on re-set (#1127)

Re-selecting a model that is already configured wiped operator-set attributes on it.
The write path rebuilt the Models[role] entry from scratch via ModelEntryWriter, which
only writes modalities it was handed (a probe result). Modalities have no CLI input and
can only be hand-edited, so a manual 'model set' (or a context-window tweak, or the TUI
picker re-selecting the same model) passed null and silently deleted a hand-set
InputModalities/OutputModalities — the concrete #1127 loss.

Add ModelEntryWriter.WriteRole, a non-destructive persist: when the role already points
at the same (provider, modelId), preserve the existing modalities and context window the
caller did not supply; switching to a different model still starts clean (old attributes
belonged to the old model). Routed 'model set' and the TUI model manager through it.

Verified against the shipped binary: on stock beta 0.25.0, 'model set main <same-model>
--context-window N' wipes InputModalities; with this fix the same command preserves it.

No config-shape or schema change, so this is fully backwards compatible.

Tests: WriteRole_SameModelWithoutModalities_PreservesHandSetModalities,
WriteRole_DifferentModel_DropsPreviousModelModalities.

* fix(cli): make model-set metadata operator-owned; discovery never clobbers it

Hardens the non-destructive `model set`/picker rewrite (#1127) against every issue
surfaced reviewing #1610, and closes the loop on modality overrides.

ContextWindow and modalities are documented to "take precedence over provider-reported
capability detection", so they are now treated as operator-owned overrides with a single
precedence rule: explicit operator input > existing stored value > probe. A fresh probe
seeds a first-time set or a model switch but never overwrites a value already on disk.

Changes:

1. ContextWindow clamp preserved on same-model re-set. WriteRole takes the explicit
   --context-window and the probe default separately; the old callers collapsed them
   (`contextWindow ?? discovered`), so probe/picker paths always passed a non-null value
   and the operator's clamp was overwritten on every re-selection.

2. Modalities are no longer silently overwritten by discovery. Previously a probe that
   reported modalities replaced a stored override (the #1127 loss's twin); now the stored
   value wins, matching the field's "manual override bypasses detection" contract.

3. Operators can change/remove those overrides. Since discovery no longer edits them, add
   `--input-modalities`, `--output-modalities`, and `--clear-modalities` to `model set`.
   Explicit set replaces the stored value; clear removes it (runtime detection resolves).
   Supplying any of them (like --context-window) skips the probe as manual configuration.

4. Corrupt/legacy existing entry no longer aborts the command. ReadSameModelEntry guards
   the deserialize (catch JsonException): an unreadable entry (e.g. an unrecognized modality
   enum string) degrades to "nothing to preserve" and the command overwrites/repairs it.

5. No false-match on ModelReference defaults. Provider/ModelId default to the stock
   local-ollama model, so an entry omitting either key deserialized to that default and
   would false-match a re-set of the stock model; preservation now requires both keys.

6. Provenance not downgraded. A same-model re-set that did not re-resolve the ID (no probe
   → Manual) keeps a previously discovered origin (Live/Defaults); only a fresh discovery
   updates it.

Tests: ModelEntryWriter unit coverage for each precedence path (clamp-over-probe, probe-
does-not-override-existing-modalities, explicit set, clear-over-probe, first-time seeding,
default-model false-match, corrupt-entry overwrite, provenance preserve/update) plus CLI
end-to-end coverage for the new flags. Full CLI suite green; slopwatch clean; model-manager
smoke tape passes.

* fix(cli): harden model-set overrides + add --clear-context-window (#1610)

Addresses code-review findings on the non-destructive model-set change:

- probe gate: only --context-window short-circuits the probe; a modality flag
  no longer skips model-existence validation and context-window discovery
- preservation read: a corrupt modality enum string no longer discards a valid
  operator-owned ContextWindow (field-tolerant recovery)
- arg parsing: missing flag values and unknown args fail loudly instead of
  being silently dropped
- cleared modality is now sticky: discovery is hands-off once a same-model
  entry exists, so a later probe cannot resurrect a --clear-modalities removal
- TryParseModalities rejects raw numeric strings (named flags only)
- provenance: preserve a prior discovered origin on any non-Live re-set
  (was only guarding Manual)
- new --clear-context-window flag to force window re-detection (symmetry with
  --clear-modalities)

Also hardens LoadModelSelection: a corrupt/legacy config no longer crashes
`model set` (repairs it) or `model list` (reports it cleanly) or the TUI.

Generalizes ModalityOverride into a shared ValueOverride<T> tri-state.
Updates netclaw-operations skill (providers.md). Docs website tracked in
netclaw-dev/netclaw-website#83.

* feat(config): preserve model definitions across role switches

* fix(config): validate named model role references

* fix(cli): preserve models when editing providers
---
 docs/spec/configuration.md                    |  49 +-
 .../.system/files/netclaw-operations/SKILL.md |   2 +-
 .../references/providers.md                   |  31 +-
 .../.openspec.yaml                            |   2 +
 .../design.md                                 |  59 +++
 .../proposal.md                               |  34 ++
 .../specs/named-model-definitions/spec.md     |  50 ++
 .../specs/netclaw-cli/spec.md                 |  15 +
 .../specs/netclaw-model-providers/spec.md     |  21 +
 .../specs/netclaw-testing/spec.md             |  16 +
 .../tasks.md                                  |  20 +
 scripts/docker/test-model-config-upgrade.sh   |  92 ++++
 .../Config/ModelEntryWriterTests.cs           | 327 ++++++++++++-
 .../Doctor/DoctorFixServiceTests.cs           |  35 ++
 .../Model/ModelCommandTests.cs                | 266 ++++++++++-
 .../Tui/ModelManagerViewModelTests.cs         |  43 +-
 .../Tui/Wizard/SectionEditorLeafTests.cs      |   2 +
 .../Tui/Wizard/WizardConfigBuilderTests.cs    |   4 +-
 src/Netclaw.Cli/Config/ConfigFileHelper.cs    |  32 +-
 src/Netclaw.Cli/Config/ModelEntryWriter.cs    | 452 ++++++++++++++++++
 .../Doctor/ChatClientDoctorCheck.cs           |   2 +-
 .../Doctor/ContextWindowDoctorCheck.cs        |  18 +-
 src/Netclaw.Cli/Doctor/DoctorFixService.cs    |  35 +-
 src/Netclaw.Cli/Model/ModelCommand.cs         | 260 ++++++++--
 src/Netclaw.Cli/Program.cs                    |   3 +-
 src/Netclaw.Cli/Provider/ProviderRenamer.cs   |  21 +
 src/Netclaw.Cli/Tui/ModelManagerViewModel.cs  |  27 +-
 .../Tui/Wizard/Steps/ProviderStepViewModel.cs |   8 +-
 .../Tui/Wizard/WizardConfigBuilder.cs         |  17 +-
 .../NamedModelConfigurationTests.cs           |  86 ++++
 .../ProviderRuntimeValidationTests.cs         |  34 ++
 .../NamedModelConfiguration.cs                | 126 +++++
 .../ProviderRuntimeValidation.cs              |  55 +++
 .../Schemas/netclaw-config.v1.schema.json     |  42 +-
 src/Netclaw.Daemon/Program.cs                 |  14 +-
 tests/smoke/assertions/init-wizard.sh         |   5 +-
 36 files changed, 2196 insertions(+), 109 deletions(-)
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/.openspec.yaml
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/design.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/proposal.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/specs/named-model-definitions/spec.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-cli/spec.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-model-providers/spec.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-testing/spec.md
 create mode 100644 openspec/changes/preserve-model-definitions-across-role-switches/tasks.md
 create mode 100755 scripts/docker/test-model-config-upgrade.sh
 create mode 100644 src/Netclaw.Configuration.Tests/NamedModelConfigurationTests.cs
 create mode 100644 src/Netclaw.Configuration/NamedModelConfiguration.cs

diff --git a/docs/spec/configuration.md b/docs/spec/configuration.md
index 94dd1a787..388e974af 100644
--- a/docs/spec/configuration.md
+++ b/docs/spec/configuration.md
@@ -103,24 +103,28 @@ keys used by model references.
 
 ### Models
 
-Named model roles. Each role points to a provider and model ID.
+Named model definitions own provider/model identity and metadata. Roles reference definitions,
+so changing Main or Fallback does not destroy overrides belonging to the previous model.
 
 ```json
 {
   "Models": {
-    "Main": {
+    "Definitions": {
+      "qwen-main": {
       "Provider": "remote-gpu",
       "ModelId": "qwen3:30b",
       "ContextWindow": 32768
+      },
+      "qwen-small": {
+        "Provider": "remote-gpu",
+        "ModelId": "qwen3:8b",
+        "ContextWindow": 32768
+      }
     },
-    "Fallback": {
-      "Provider": "remote-gpu",
-      "ModelId": "qwen3:8b",
-      "ContextWindow": 32768
-    },
-    "Compaction": {
-      "Provider": "remote-gpu",
-      "ModelId": "qwen3:8b"
+    "Roles": {
+      "Main": "qwen-main",
+      "Fallback": "qwen-small",
+      "Compaction": "qwen-small"
     }
   }
 }
@@ -481,8 +485,9 @@ following the standard .NET convention.
 
 ```bash
 # Override the main model
-export NETCLAW_Models__Main__Provider="openrouter"
-export NETCLAW_Models__Main__ModelId="anthropic/claude-sonnet-4"
+export NETCLAW_Models__Definitions__claude__Provider="openrouter"
+export NETCLAW_Models__Definitions__claude__ModelId="anthropic/claude-sonnet-4"
+export NETCLAW_Models__Roles__Main="claude"
 
 # Set a provider API key
 export NETCLAW_Providers__openrouter__ApiKey="sk-or-v1-..."
@@ -520,14 +525,20 @@ export NETCLAW_Session__MaxToolIterationsPerTurn="60"
     }
   },
   "Models": {
-    "Main": {
-      "Provider": "local",
-      "ModelId": "qwen3:30b",
-      "ContextWindow": 32768
+    "Definitions": {
+      "qwen-main": {
+        "Provider": "local",
+        "ModelId": "qwen3:30b",
+        "ContextWindow": 32768
+      },
+      "qwen-small": {
+        "Provider": "local",
+        "ModelId": "qwen3:8b"
+      }
     },
-    "Compaction": {
-      "Provider": "local",
-      "ModelId": "qwen3:8b"
+    "Roles": {
+      "Main": "qwen-main",
+      "Compaction": "qwen-small"
     }
   },
   "Session": {
diff --git a/feeds/skills/.system/files/netclaw-operations/SKILL.md b/feeds/skills/.system/files/netclaw-operations/SKILL.md
index 4980ff49e..46df1398d 100644
--- a/feeds/skills/.system/files/netclaw-operations/SKILL.md
+++ b/feeds/skills/.system/files/netclaw-operations/SKILL.md
@@ -3,7 +3,7 @@ name: netclaw-operations
 description: "REQUIRED when the user asks about scheduling, reminders, cron jobs, timers, background jobs, diagnostics, troubleshooting, MCP tools, daemon health, identity updates, or Netclaw capabilities and self-maintenance."
 metadata:
   author: netclaw
-  version: "2.24.1"
+  version: "2.26.0"
 ---
 
 # Netclaw Operations
diff --git a/feeds/skills/.system/files/netclaw-operations/references/providers.md b/feeds/skills/.system/files/netclaw-operations/references/providers.md
index 7e2349a83..8930557b3 100644
--- a/feeds/skills/.system/files/netclaw-operations/references/providers.md
+++ b/feeds/skills/.system/files/netclaw-operations/references/providers.md
@@ -36,7 +36,7 @@ options instead of adding provider-specific properties to `ProviderEntry`.
 ### Degraded mode: No-Op chat client
 
 When Netclaw starts without an explicitly configured main model/provider
-(no `Models:Main`, incomplete `Models:Main`, no `Providers`, or `Models:Main`
+(no `Models.Roles.Main`, an unresolved definition, no `Providers`, or the selected definition
 points to a provider that is not configured), the daemon launches in
 **degraded mode** with a No-Op chat client. Bound defaults such as
 `local-ollama/qwen3:30b` do not count as operator configuration unless those
@@ -78,6 +78,35 @@ When adding an OpenAI provider from the CLI, `netclaw provider add <name>
 openai` defaults to the ChatGPT OAuth device flow. Use `--auth api-key
 --api-key <key>` to force platform API-key auth instead.
 
+### Assigning models to roles and overriding metadata
+
+`netclaw model set <role> <provider> <model-id>` creates or reuses a named model
+definition and assigns it to a role (`main`, `fallback`, `compaction`). Definitions
+own provider/model identity and metadata, while roles only reference definitions.
+Switching away from a model and back therefore preserves its overrides. Two attributes can be overridden by the
+operator and are **operator-owned**: the context window and the input/output
+modalities. Provider discovery seeds a new definition but never changes an existing
+definition, including adding a property the definition deliberately omits.
+
+- `--context-window <tokens>` clamps the session budget and takes precedence
+  over provider-reported detection. Supplying it configures the model manually
+  and skips the metadata probe.
+- `--input-modalities <list>` / `--output-modalities <list>` override detected
+  modalities with a comma-separated list of named flags (`Text`, `Image`,
+  `Audio`, `Video`). These do **not** skip the probe — the model is still
+  validated and its context window discovered; the override just wins over the
+  discovered modalities.
+- `--clear-context-window` and `--clear-modalities` remove the respective
+  override so runtime capability detection resolves it again (use these after a
+  provider enlarges a model's window or fixes mis-reported modalities).
+
+To change a preserved value you must pass the corresponding flag (a plain
+re-set will not touch it). A legacy or hand-edited entry with an unreadable
+value does not block a re-set — `model set` migrates legacy inline roles to named
+definitions and repairs the selected entry while keeping the fields
+it can still read; `model list` reports an unparseable config instead of
+crashing, and `netclaw doctor --fix` repairs it.
+
 ### Adding GitHub Copilot
 
 GitHub Copilot uses the OAuth device flow only — no API key. The operator
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/.openspec.yaml b/openspec/changes/preserve-model-definitions-across-role-switches/.openspec.yaml
new file mode 100644
index 000000000..eb5fa80e6
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-10
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/design.md b/openspec/changes/preserve-model-definitions-across-role-switches/design.md
new file mode 100644
index 000000000..2fb5b0906
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/design.md
@@ -0,0 +1,59 @@
+## Context
+
+Model metadata is currently embedded in three runtime role entries. Those entries are both the operator's durable configuration and the runtime consumer shape, so assigning a different model destroys metadata belonging to the previous model. Existing deployments and the current stable Docker image use this legacy shape.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Store model-owned metadata once in named definitions and make roles reference definitions.
+- Keep manual JSON editing obvious: property absence means runtime detection, with no tombstones.
+- Run legacy configuration without an eager write, and migrate deterministically on explicit mutation/fix.
+- Resolve and validate references before persistence and runtime client construction.
+
+**Non-Goals:**
+
+- Downgrade compatibility after the configuration has been migrated.
+- Automatic conflict resolution or model-definition garbage collection.
+- Changes to provider discovery or actor/persistence protocols.
+
+## Decisions
+
+### New canonical shape
+
+`Models.Definitions` is a dictionary of operator-chosen names to complete `ModelReference` values. `Models.Roles` contains `Main`, `Fallback`, and `Compaction` definition-name references. Runtime code receives the existing resolved `ModelSelection`, keeping actor and chat-client boundaries unchanged.
+
+This is preferred over a hidden metadata cache or role-entry tombstones because it gives manual editors one visible source of truth and preserves property absence as runtime detection.
+
+### Dual-shape reader, single-shape writer
+
+A shared configuration resolver accepts either the complete legacy inline shape or the complete named shape. Mixed shapes, missing definitions, duplicate/invalid names, and conflicting migration candidates fail loudly. Daemon startup reads legacy configuration without rewriting it. CLI/TUI writes and `doctor --fix` migrate legacy input atomically before applying the requested mutation.
+
+The schema accepts both complete shapes during the compatibility window. New writers emit only the named shape.
+
+### Deterministic legacy migration
+
+Each distinct case-insensitive `(Provider, ModelId)` becomes one definition. A deterministic slug is derived from provider and model ID, with a stable numeric suffix for name collisions. When multiple legacy roles identify the same model, their optional metadata must agree; otherwise migration fails with the conflicting role names and fields.
+
+### Upgrade smoke
+
+The smoke harness creates a disposable directory/volume, runs the latest stable image to produce or consume a legacy configuration, stops it, builds a uniquely tagged local image, and starts that image against the same isolated volume. Assertions verify startup, legacy resolution, explicit migration, and preservation after role switching. Cleanup removes only resources carrying the test's unique label/name.
+
+## Risks / Trade-offs
+
+- **Older binaries cannot read the named shape after migration** → document that rollback requires restoring the pre-migration backup; migration writes atomically and retains a backup.
+- **Dual-shape support can become permanent complexity** → centralize it in one resolver and have every writer emit only the canonical shape.
+- **Conflicting legacy roles could be silently merged** → reject conflicts and report exact fields/roles.
+- **Docker smoke could touch operator state** → require an absolute temporary path created by the harness and unique container/image names; never use default Netclaw volumes.
+- **Stable image availability/network failures** → make the Docker upgrade scenario explicit and fail with actionable diagnostics; unit migration fixtures remain mandatory offline proof.
+
+## Migration Plan
+
+1. Ship a reader that supports both shapes and schema validation for both.
+2. Verify an untouched legacy stable configuration starts with the new daemon.
+3. On the first explicit model/config write or `doctor --fix`, validate, back up, migrate, re-resolve, then atomically persist.
+4. Document rollback as restoring the generated legacy backup before running an older image.
+
+## Open Questions
+
+- The exact stable tag is resolved from the release manifest at smoke execution time rather than hard-coded.
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/proposal.md b/openspec/changes/preserve-model-definitions-across-role-switches/proposal.md
new file mode 100644
index 000000000..ac0dd85ca
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+PRD-004 and PRD-005 allow operators to select models and override provider-reported capabilities, but the current `Models.Main` / `Fallback` / `Compaction` entries combine role assignment with model-owned metadata. Switching a role therefore destroys manually maintained context-window and modality overrides, especially for vLLM deployments that cannot report modalities.
+
+## What Changes
+
+- Add human-readable named model definitions whose metadata is independent of role assignment.
+- Make model roles reference named definitions, so switching roles does not rewrite a definition.
+- Continue accepting the existing inline role shape on upgrade and provide deterministic migration to the named shape.
+- Reject ambiguous mixed or conflicting configuration instead of silently choosing a representation.
+- Add isolated stable-container to locally-built-container upgrade smoke coverage using a disposable volume.
+- Preserve absence of optional metadata as runtime detection; no hidden tombstone values are introduced.
+
+In scope: configuration binding, CLI/TUI model assignment, schema, doctor/migration behavior, operational guidance, automated compatibility proof, and Docker upgrade smoke coverage.
+
+Out of scope: automatic model discovery beyond existing probes, changing provider APIs, and supporting downgrade from the new shape to an older Netclaw binary.
+
+## Capabilities
+
+### New Capabilities
+
+- `named-model-definitions`: Model-owned definitions, role references, legacy resolution, migration, and conflict behavior.
+
+### Modified Capabilities
+
+- `netclaw-model-providers`: Primary, fallback, and compaction assignments reference persistent model definitions.
+- `netclaw-cli`: Model commands and TUI preserve model metadata across role switches and expose migration failures.
+- `netclaw-testing`: Upgrade compatibility is proven with legacy configuration and an isolated container-volume smoke.
+
+## Impact
+
+Affected areas include `Netclaw.Configuration` model types and schema, daemon/CLI configuration binding, model CLI and TUI persistence, provider rename behavior, doctor repair, system operational guidance, and smoke tooling. Startup remains fail-closed for invalid references. Existing inline deployments remain readable and runnable without an eager startup rewrite.
+
+Security impact is limited to configuration integrity: unresolved or conflicting role references fail before persistence or runtime client construction. Operationally, configuration is migrated only by an explicit writing/fix operation, and the upgrade smoke never mounts the operator's real Netclaw home.
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/specs/named-model-definitions/spec.md b/openspec/changes/preserve-model-definitions-across-role-switches/specs/named-model-definitions/spec.md
new file mode 100644
index 000000000..fc4a2fdbf
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/specs/named-model-definitions/spec.md
@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Model-owned named definitions
+The system SHALL store provider identity, model ID, context-window override, modality overrides, and provenance in named model definitions independent of runtime role assignment. Roles SHALL reference definitions by name.
+
+#### Scenario: Switching away and back preserves overrides
+- **GIVEN** definition `vision` has a manual `InputModalities` override
+- **WHEN** Main switches from `vision` to another definition and back
+- **THEN** the `vision` definition SHALL remain unchanged
+- **AND** Main SHALL resolve to its original override
+
+#### Scenario: Manual absence remains runtime detection
+- **GIVEN** an existing definition omits an optional capability property
+- **WHEN** the definition is assigned to another role
+- **THEN** the property SHALL remain absent
+- **AND** no tombstone or discovered replacement SHALL be persisted
+
+### Requirement: Legacy model configuration compatibility
+The system SHALL accept the legacy inline Main/Fallback/Compaction shape without rewriting it during startup and SHALL resolve it to the same runtime model selection.
+
+#### Scenario: Existing deployment starts after upgrade
+- **GIVEN** a valid configuration written by the latest stable Netclaw image
+- **WHEN** the upgraded daemon starts
+- **THEN** startup SHALL succeed with equivalent model role values and capabilities
+- **AND** the configuration file SHALL not be rewritten merely by startup
+
+#### Scenario: Explicit mutation migrates legacy shape
+- **GIVEN** a valid legacy configuration
+- **WHEN** an operator performs a model-writing command or runs doctor fix
+- **THEN** the system SHALL atomically persist the named shape before completing the mutation
+- **AND** the persisted named shape SHALL resolve to the same runtime values
+
+#### Scenario: Ambiguous shape fails loudly
+- **GIVEN** configuration contains both legacy role objects and named role references
+- **WHEN** configuration is validated or loaded
+- **THEN** the operation SHALL fail with remediation identifying the mixed shape
+
+### Requirement: Reference integrity
+Every persisted role reference SHALL resolve to an existing definition before persistence and startup.
+
+#### Scenario: Missing definition is rejected
+- **WHEN** a role references an unknown definition
+- **THEN** validation SHALL fail before runtime client construction
+- **AND** no partial configuration write SHALL occur
+
+#### Scenario: Conflicting legacy duplicates are rejected
+- **GIVEN** two legacy roles identify the same provider/model but contain conflicting overrides
+- **WHEN** migration is requested
+- **THEN** migration SHALL fail with the conflicting roles and fields
+- **AND** the legacy file SHALL remain unchanged
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-cli/spec.md b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-cli/spec.md
new file mode 100644
index 000000000..d8c2383e3
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-cli/spec.md
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Named model role management
+Model CLI and TUI operations SHALL assign roles by changing references and SHALL edit model metadata only through the selected definition.
+
+#### Scenario: Assign existing definition
+- **WHEN** an operator assigns an existing named definition to Main
+- **THEN** only the Main role reference SHALL change
+- **AND** no definition metadata SHALL change
+
+#### Scenario: Mutating legacy configuration
+- **GIVEN** the CLI loads a valid legacy model configuration
+- **WHEN** a model mutation is requested
+- **THEN** the CLI SHALL migrate and validate the canonical shape before persistence
+- **AND** failure SHALL leave the original file unchanged
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-model-providers/spec.md b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-model-providers/spec.md
new file mode 100644
index 000000000..5743dded3
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-model-providers/spec.md
@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: Primary and fallback model
+The system SHALL support configuring primary, fallback, and compaction roles as references to persistent named model definitions. Changing a role SHALL NOT change the referenced definition. When the primary model is unavailable due to rate limiting, timeout, or error, the system SHALL automatically switch to the fallback model. Fallback activation SHALL be logged for operator visibility.
+
+#### Scenario: Primary model succeeds
+- **GIVEN** both primary and fallback roles reference valid definitions
+- **WHEN** the primary model responds successfully
+- **THEN** the primary model response SHALL be used
+- **AND** no fallback activation SHALL occur
+
+#### Scenario: Automatic fallback on primary failure
+- **GIVEN** both primary and fallback roles reference valid definitions
+- **WHEN** the primary model returns a rate limit, timeout, or error response
+- **THEN** the system SHALL retry using the fallback definition
+- **AND** a log entry SHALL record the fallback activation with the failure reason
+
+#### Scenario: Role switch preserves model definition
+- **GIVEN** a named model definition contains operator capability overrides
+- **WHEN** Main or Fallback is assigned to another definition
+- **THEN** the previous definition SHALL remain unchanged and available for reassignment
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-testing/spec.md b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-testing/spec.md
new file mode 100644
index 000000000..833a552fd
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/specs/netclaw-testing/spec.md
@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: Container upgrade compatibility proof
+The smoke suite SHALL verify upgrade from the latest stable Netclaw container to a locally built image using only an isolated temporary configuration volume.
+
+#### Scenario: Stable-to-local upgrade
+- **GIVEN** the latest stable image has written or consumed a legacy config in a disposable volume
+- **WHEN** a uniquely tagged local image starts against the same volume
+- **THEN** the new image SHALL become healthy without modifying the file on startup
+- **AND** an explicit migration SHALL preserve effective role and capability values
+- **AND** switching away from and back to a definition SHALL preserve its overrides
+
+#### Scenario: Production state isolation
+- **WHEN** the upgrade smoke runs
+- **THEN** it SHALL use a newly created absolute temporary directory or uniquely named test volume
+- **AND** it SHALL NOT mount or inspect the default or operator-provided Netclaw home
diff --git a/openspec/changes/preserve-model-definitions-across-role-switches/tasks.md b/openspec/changes/preserve-model-definitions-across-role-switches/tasks.md
new file mode 100644
index 000000000..1d03f3282
--- /dev/null
+++ b/openspec/changes/preserve-model-definitions-across-role-switches/tasks.md
@@ -0,0 +1,20 @@
+## 1. Canonical configuration and compatibility
+
+- [x] 1.1 Add named definition and role-reference configuration types plus one resolver for legacy and canonical shapes
+- [x] 1.2 Add deterministic, conflict-detecting legacy migration with atomic persistence and backup behavior
+- [x] 1.3 Update the JSON schema to accept legacy or canonical models while rejecting mixed/invalid shapes
+- [x] 1.4 Route daemon, CLI, doctor, provider rename, wizard, and TUI consumers through resolved canonical configuration
+
+## 2. Operator workflows
+
+- [x] 2.1 Update model CLI commands to create/edit definitions and switch roles without mutating definitions
+- [x] 2.2 Update the model-manager TUI and initialization writer to emit canonical configuration
+- [x] 2.3 Update `netclaw-operations` guidance and CLI help, including migration and rollback behavior
+
+## 3. Automated proof
+
+- [x] 3.1 Add legacy load, conflict rejection, canonical round-trip, and role A→B→A preservation tests
+- [x] 3.2 Add CLI/TUI tests proving invalid references are rejected before persistence
+- [x] 3.3 Add isolated latest-stable-container → local-image upgrade smoke and semantic assertions
+- [ ] 3.4 Run targeted/full tests, native TUI smoke, evals, Slopwatch, and copyright verification
+- [x] 3.5 Validate OpenSpec implementation alignment and prepare spec synchronization
diff --git a/scripts/docker/test-model-config-upgrade.sh b/scripts/docker/test-model-config-upgrade.sh
new file mode 100755
index 000000000..7623cf3c4
--- /dev/null
+++ b/scripts/docker/test-model-config-upgrade.sh
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Verify that the latest stable image's inline model configuration survives an upgrade to a
+# locally built image and migrates without losing operator-owned model metadata.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/docker/lib/smoke-lib.sh
+. "$SCRIPT_DIR/lib/smoke-lib.sh"
+
+LOCAL_IMAGE="${1:?usage: test-model-config-upgrade.sh <local-image> [stable-image]}"
+STABLE_IMAGE="${2:-ghcr.io/netclaw-dev/netclaw:latest}"
+RUN_ID="model-upgrade-$PPID-$$"
+CONTAINER="netclaw-$RUN_ID"
+ROOT="$(mktemp -d -t netclaw-model-upgrade.XXXXXX)"
+HOME_DIR="$ROOT/home"
+CONFIG_DIR="$HOME_DIR/config"
+CONFIG="$CONFIG_DIR/netclaw.json"
+
+cleanup() {
+    docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+    docker run --rm --entrypoint chmod -v "$ROOT:/cleanup" "$LOCAL_IMAGE" \
+        -R a+rwX /cleanup >/dev/null 2>&1 || true
+    rm -rf "$ROOT"
+}
+trap cleanup EXIT
+
+mkdir -p "$CONFIG_DIR"
+chmod 0777 "$HOME_DIR" "$CONFIG_DIR"
+
+cat >"$CONFIG" <<'JSON'
+{
+  "configVersion": 1,
+  "Providers": {
+    "vllm": {
+      "Type": "openai-compatible",
+      "Endpoint": "http://127.0.0.1:8000"
+    }
+  },
+  "Models": {
+    "Main": {
+      "Provider": "vllm",
+      "ModelId": "qwen-vl",
+      "ContextWindow": 32768,
+      "InputModalities": "Text, Image",
+      "OutputModalities": "Text"
+    },
+    "Fallback": {
+      "Provider": "vllm",
+      "ModelId": "llama-text"
+    }
+  }
+}
+JSON
+chmod 0666 "$CONFIG"
+
+echo "==> Latest stable consumes the isolated legacy configuration: $STABLE_IMAGE"
+docker run --rm --entrypoint /usr/local/bin/netclaw \
+    -v "$HOME_DIR:/home/netclaw/.netclaw" "$STABLE_IMAGE" model list >/dev/null
+
+legacy_hash="$(sha256sum "$CONFIG" | awk '{print $1}')"
+
+echo "==> Locally built daemon starts against the same legacy configuration without rewriting it"
+docker run -d --name "$CONTAINER" -v "$HOME_DIR:/home/netclaw/.netclaw" "$LOCAL_IMAGE" >/dev/null
+netclaw_wait_healthy "$CONTAINER" 5199 60
+[[ "$(sha256sum "$CONFIG" | awk '{print $1}')" == "$legacy_hash" ]] \
+    || { echo "ERROR: startup rewrote the legacy configuration" >&2; exit 1; }
+docker rm -f "$CONTAINER" >/dev/null
+
+run_local_cli() {
+    docker run --rm --entrypoint /usr/local/bin/netclaw \
+        -v "$HOME_DIR:/home/netclaw/.netclaw" "$LOCAL_IMAGE" "$@"
+}
+
+echo "==> Explicit model mutation migrates, then A -> B -> A preserves A's overrides"
+run_local_cli model set main vllm llama-text --context-window 65536 >/dev/null
+run_local_cli model set main vllm qwen-vl >/dev/null
+
+jq -e '
+  .Models.Main == null and
+  .Models.Roles.Main as $active |
+  .Models.Definitions[$active] |
+  .Provider == "vllm" and
+  .ModelId == "qwen-vl" and
+  .ContextWindow == 32768 and
+  .InputModalities == "Text, Image" and
+  .OutputModalities == "Text"
+' "$CONFIG" >/dev/null
+
+test -f "$CONFIG.legacy-models.bak"
+jq -e '.Models.Main.ModelId == "qwen-vl"' "$CONFIG.legacy-models.bak" >/dev/null
+
+echo "✓ stable legacy config starts unchanged, migrates explicitly, and preserves model metadata"
diff --git a/src/Netclaw.Cli.Tests/Config/ModelEntryWriterTests.cs b/src/Netclaw.Cli.Tests/Config/ModelEntryWriterTests.cs
index 01e2ae467..28101310c 100644
--- a/src/Netclaw.Cli.Tests/Config/ModelEntryWriterTests.cs
+++ b/src/Netclaw.Cli.Tests/Config/ModelEntryWriterTests.cs
@@ -3,9 +3,12 @@
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
 // -----------------------------------------------------------------------
+using System.Text.Json;
 using Netclaw.Cli.Config;
 using Netclaw.Configuration;
 using Xunit;
+using ModalityOverride = Netclaw.Cli.Config.ValueOverride<Netclaw.Configuration.ModelModality>;
+using ContextWindowOverride = Netclaw.Cli.Config.ValueOverride<int>;
 
 namespace Netclaw.Cli.Tests.Config;
 
@@ -13,7 +16,8 @@ namespace Netclaw.Cli.Tests.Config;
 /// Guards the single persist path shared by `model set`, the init wizard, and the TUI
 /// model manager. The rule under test: modalities are written only when the discovery
 /// source genuinely reported them, so an unknown is never frozen into config as a
-/// permanent "Text" override (#1290).
+/// permanent "Text" override (#1290), and operator-owned overrides survive re-selection
+/// (#1127 / #1610).
 /// </summary>
 public class ModelEntryWriterTests
 {
@@ -57,4 +61,325 @@ public void BuildModelEntry_BlankModelIdAndNullProvenance_OmitsBoth()
         Assert.False(entry.ContainsKey("ModelId"));
         Assert.False(entry.ContainsKey("Provenance"));
     }
+
+    [Fact]
+    public void WriteRole_SameModelWithoutModalities_PreservesHandSetModalities()
+    {
+        // On-disk shape: an operator-set InputModalities override.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "ContextWindow": 262144, "InputModalities": "Text, Image" } }
+            """);
+
+        // Re-set the same model with only a context-window change; no modality intent supplied.
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Set(131072), ModalityOverride.Unset, ModalityOverride.Unset, discovered: null);
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("Text, Image", entry["InputModalities"]); // preserved (#1127)
+        Assert.Equal(131072, entry["ContextWindow"]);          // explicit override applied
+    }
+
+    [Fact]
+    public void WriteRole_SameModel_PreservesExistingClampOverDiscoveredWindow()
+    {
+        // Operator clamped ContextWindow below what the provider reports.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "ContextWindow": 32000 } }
+            """);
+
+        // Re-select the same model (picker path): no explicit --context-window, but the probe
+        // reports the model's full window. The operator's clamp must win (#1610): ContextWindow
+        // is documented to take precedence over provider-reported detection.
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal(32000, entry["ContextWindow"]);
+    }
+
+    [Fact]
+    public void WriteRole_FirstTimeSet_UsesDiscoveredWindow()
+    {
+        // No existing entry for the role: discovery is the fallback that seeds the value.
+        var models = new Dictionary<string, object>();
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal(128000, entry["ContextWindow"]);
+    }
+
+    [Fact]
+    public void WriteRole_ClearContextWindow_DropsStoredClampAndDiscoveredWindow()
+    {
+        // Operator clamped the window; now --clear-context-window removes the clamp so runtime
+        // detection resolves it. Clear wins over BOTH the stored value and a probe that reports
+        // a window (#1610) — mirroring --clear-modalities.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "ContextWindow": 32000 } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Clear, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.False(entry.ContainsKey("ContextWindow")); // clamp removed → runtime detection
+    }
+
+    [Fact]
+    public void WriteRole_SameDefinitionWithoutWindow_DiscoveryDoesNotResurrect()
+    {
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        Assert.False(ActiveEntry(models, "Main").ContainsKey("ContextWindow"));
+    }
+
+    [Fact]
+    public void WriteRole_SameModelFreshProbe_DoesNotOverrideExistingModalities()
+    {
+        // Operator override on disk; a fresh probe reports a coarser Text-only capability.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "InputModalities": "Text, Image" } }
+            """);
+
+        // The stored override wins — discovery never silently overwrites it (#1610 / #5). This is
+        // the same rule as ContextWindow: the field is documented to bypass automated detection.
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(input: ModelModality.Text, output: ModelModality.Text));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("Text, Image", entry["InputModalities"]);
+    }
+
+    [Fact]
+    public void WriteRole_SameModelEntryClearedModality_DiscoveryDoesNotResurrect()
+    {
+        // The entry exists for this model but carries NO modality — the on-disk shape left behind
+        // by a prior --clear-modalities. A later same-model re-set that carries a probe result must
+        // NOT re-add the discovered modality, or it would silently undo the operator's clear and
+        // re-demote a multimodal-misreporting model on next boot (#1610).
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(input: ModelModality.Text | ModelModality.Image));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.False(entry.ContainsKey("InputModalities")); // stays cleared, not resurrected
+    }
+
+    [Fact]
+    public void WriteRole_ExplicitModalityOverride_ReplacesExisting()
+    {
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "InputModalities": "Text, Image" } }
+            """);
+
+        // Explicit operator input (--input-modalities Text) is the authority: it replaces the
+        // stored override so the operator can actually change a value discovery no longer touches.
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Unset,
+            ModalityOverride.Set(ModelModality.Text), ModalityOverride.Unset, discovered: null);
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("Text", entry["InputModalities"]);
+    }
+
+    [Fact]
+    public void WriteRole_ClearModalities_RemovesOverrideEvenWhenProbeReportsOne()
+    {
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "InputModalities": "Text, Image", "OutputModalities": "Text" } }
+            """);
+
+        // --clear-modalities removes both overrides so runtime detection resolves them; clear
+        // wins over BOTH the stored value and a probe that still reports modalities (#1610 / #4).
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Unset, ModalityOverride.Clear, ModalityOverride.Clear,
+            Discovered(input: ModelModality.Text | ModelModality.Image));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.False(entry.ContainsKey("InputModalities"));
+        Assert.False(entry.ContainsKey("OutputModalities"));
+    }
+
+    [Fact]
+    public void WriteRole_ExistingEntryOmitsModelId_DoesNotFalseMatchDefaultModel()
+    {
+        // The entry omits ModelId; ModelReference would default it to the stock "qwen3:30b".
+        // Setting the stock default model must NOT treat this as the same model and carry the
+        // stray modalities onto a model the entry never named (#1610).
+        var models = Models(
+            """
+            { "Main": { "Provider": "local-ollama", "InputModalities": "Text, Image" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "local-ollama", "qwen3:30b", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset, discovered: null);
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("qwen3:30b", entry["ModelId"]);
+        Assert.False(entry.ContainsKey("InputModalities")); // stray modality dropped, not carried over
+    }
+
+    [Theory]
+    [InlineData(ModelDiscoverySource.Live, ModelDiscoverySource.Manual, ModelDiscoverySource.Live)]
+    [InlineData(ModelDiscoverySource.Live, ModelDiscoverySource.Defaults, ModelDiscoverySource.Live)]
+    [InlineData(ModelDiscoverySource.Defaults, ModelDiscoverySource.Live, ModelDiscoverySource.Live)]
+    public void WriteRole_SameModel_PreservesProvenanceUnlessFreshlyDiscovered(
+        ModelDiscoverySource existing,
+        ModelDiscoverySource incoming,
+        ModelDiscoverySource expected)
+    {
+        var models = Models(
+            $$"""
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "Provenance": "{{existing}}" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", incoming,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset, discovered: null);
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal(expected.ToString(), entry["Provenance"]);
+    }
+
+    [Fact]
+    public void WriteRole_CorruptExistingEntry_OverwritesInsteadOfThrowing()
+    {
+        // A legacy/hand-corrupted entry: "Vision" is not a valid ModelModality enum name, so
+        // deserializing it throws JsonException. `model set` must still succeed and repair it
+        // (#1610) rather than aborting on an entry it is about to overwrite.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "InputModalities": "Vision" } }
+            """);
+
+        var ex = Record.Exception(() => ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000)));
+
+        Assert.Null(ex);
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("qwen-vl", entry["ModelId"]);
+        Assert.False(entry.ContainsKey("ContextWindow"));      // existing absence stays runtime detection
+        Assert.False(entry.ContainsKey("InputModalities"));    // corrupt value dropped, not frozen
+    }
+
+    [Fact]
+    public void WriteRole_CorruptModalityButValidWindow_PreservesWindow()
+    {
+        // A hand-edited entry with a VALID ContextWindow clamp but an unparseable InputModalities
+        // string. Discarding the whole entry (the old catch behavior) would silently clobber the
+        // operator's still-valid window; the field-tolerant read must preserve it (#1610).
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "ContextWindow": 32768, "InputModalities": "text_and_image" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal(32768, entry["ContextWindow"]);         // operator clamp preserved, not clobbered
+        Assert.False(entry.ContainsKey("InputModalities"));  // unparseable override dropped
+    }
+
+    [Fact]
+    public void WriteRole_CorruptEntryForDifferentModel_DoesNotLeakWindow()
+    {
+        // A corrupt entry that names a DIFFERENT model must not have its ContextWindow carried
+        // onto the model being set — the resilient read only preserves a same-model entry.
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "other-model", "ContextWindow": 32768, "InputModalities": "Vision" } }
+            """);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Live,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset,
+            Discovered(contextWindow: 128000));
+
+        var entry = ActiveEntry(models, "Main");
+        Assert.Equal("qwen-vl", entry["ModelId"]);
+        Assert.Equal(128000, entry["ContextWindow"]);  // discovered window, not the other model's 32768
+    }
+
+    [Fact]
+    public void WriteRole_SwitchAwayAndBack_PreservesPreviousModelModalities()
+    {
+        var models = Models(
+            """
+            { "Main": { "Provider": "spark", "ModelId": "qwen-vl", "InputModalities": "Text, Image" } }
+            """);
+
+        // Switching roles changes only the role reference. The old definition remains intact.
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "other-model", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset, discovered: null);
+
+        Assert.Equal("other-model", ActiveEntry(models, "Main")["ModelId"]);
+
+        ModelEntryWriter.WriteRole(
+            models, "Main", "spark", "qwen-vl", ModelDiscoverySource.Manual,
+            ContextWindowOverride.Unset, ModalityOverride.Unset, ModalityOverride.Unset, discovered: null);
+
+        Assert.Equal("Text, Image", ActiveEntry(models, "Main")["InputModalities"]);
+    }
+
+    private static Dictionary<string, object> Models(string json)
+        => JsonSerializer.Deserialize<Dictionary<string, object>>(json)!;
+
+    private static Dictionary<string, object> ActiveEntry(
+        Dictionary<string, object> models, string role)
+    {
+        var roles = (Dictionary<string, object>)models["Roles"];
+        var definitionName = (string)roles[role];
+        var definitions = (Dictionary<string, object>)models["Definitions"];
+        return (Dictionary<string, object>)definitions[definitionName];
+    }
+
+    private static DiscoveredModel Discovered(
+        int? contextWindow = null, ModelModality? input = null, ModelModality? output = null)
+        => new()
+        {
+            ModelId = new ModelId("qwen-vl"),
+            ContextWindowTokens = contextWindow,
+            InputModalities = input,
+            OutputModalities = output,
+        };
 }
diff --git a/src/Netclaw.Cli.Tests/Doctor/DoctorFixServiceTests.cs b/src/Netclaw.Cli.Tests/Doctor/DoctorFixServiceTests.cs
index f673b5443..245bb3d22 100644
--- a/src/Netclaw.Cli.Tests/Doctor/DoctorFixServiceTests.cs
+++ b/src/Netclaw.Cli.Tests/Doctor/DoctorFixServiceTests.cs
@@ -4,6 +4,7 @@
 // </copyright>
 // -----------------------------------------------------------------------
 using Netclaw.Cli.Daemon;
+using System.Text.Json;
 using Netclaw.Cli.Doctor;
 using Netclaw.Configuration;
 using Xunit;
@@ -19,6 +20,40 @@ public sealed class DoctorFixServiceTests
     // ── Config-file fixes (systemd PATH rehydration disabled so these stay hermetic
     //    on machines where netclaw is actually installed as a --user service) ──
 
+    [Fact]
+    public async Task MigratesLegacyModelsWithoutChangingEffectiveMetadata()
+    {
+        var paths = NewPaths();
+        await File.WriteAllTextAsync(paths.NetclawConfigPath,
+            """
+            {
+              "configVersion": 1,
+              "Models": {
+                "Main": {
+                  "Provider": "vllm",
+                  "ModelId": "qwen-vl",
+                  "ContextWindow": 32768,
+                  "InputModalities": "Text, Image"
+                }
+              }
+            }
+            """, TestContext.Current.CancellationToken);
+
+        var service = ConfigOnlyService(paths);
+        var plan = await service.BuildPlanAsync(TestContext.Current.CancellationToken);
+        await service.ApplyAsync(plan, TestContext.Current.CancellationToken);
+
+        using var document = JsonDocument.Parse(await File.ReadAllTextAsync(
+            paths.NetclawConfigPath, TestContext.Current.CancellationToken));
+        var models = document.RootElement.GetProperty("Models");
+        var name = models.GetProperty("Roles").GetProperty("Main").GetString()!;
+        var definition = models.GetProperty("Definitions").GetProperty(name);
+        Assert.Equal("qwen-vl", definition.GetProperty("ModelId").GetString());
+        Assert.Equal(32768, definition.GetProperty("ContextWindow").GetInt32());
+        Assert.Equal("Text, Image", definition.GetProperty("InputModalities").GetString());
+        Assert.True(File.Exists(paths.NetclawConfigPath + ".legacy-models.bak"));
+    }
+
     [Fact]
     public async Task PlansConfigVersionFix_WhenMissing()
     {
diff --git a/src/Netclaw.Cli.Tests/Model/ModelCommandTests.cs b/src/Netclaw.Cli.Tests/Model/ModelCommandTests.cs
index 72de9fade..b541261d7 100644
--- a/src/Netclaw.Cli.Tests/Model/ModelCommandTests.cs
+++ b/src/Netclaw.Cli.Tests/Model/ModelCommandTests.cs
@@ -88,7 +88,7 @@ public async Task Set_MainModel_WritesConfig()
 
         var config = ReadConfigFile(_paths.NetclawConfigPath);
         Assert.True(config.RootElement.TryGetProperty("Models", out var models));
-        Assert.True(models.TryGetProperty("Main", out var main));
+        var main = ReadActiveModel(config, "Main");
         Assert.Equal("my-ollama", main.GetProperty("Provider").GetString());
         Assert.Equal("qwen3:30b", main.GetProperty("ModelId").GetString());
         Assert.Equal("Manual", main.GetProperty("Provenance").GetString());
@@ -127,7 +127,7 @@ public async Task Set_OpenAiOAuthModel_StoresLiveDiscoveredMetadata()
 
         Assert.Equal(0, exitCode);
         var config = ReadConfigFile(_paths.NetclawConfigPath);
-        var main = config.RootElement.GetProperty("Models").GetProperty("Main");
+        var main = ReadActiveModel(config, "Main");
         Assert.Equal("Live", main.GetProperty("Provenance").GetString());
         Assert.Equal(512000, main.GetProperty("ContextWindow").GetInt32());
         Assert.Equal("Text, Image", main.GetProperty("InputModalities").GetString());
@@ -354,8 +354,9 @@ public async Task Clear_Fallback_RemovesFromConfig()
 
         var config = ReadConfigFile(_paths.NetclawConfigPath);
         Assert.True(config.RootElement.TryGetProperty("Models", out var models));
-        Assert.True(models.TryGetProperty("Main", out _)); // Main still exists
-        Assert.False(models.TryGetProperty("Fallback", out _)); // Fallback removed
+        var roles = models.GetProperty("Roles");
+        Assert.True(roles.TryGetProperty("Main", out _)); // Main still exists
+        Assert.False(roles.TryGetProperty("Fallback", out _)); // Fallback removed
     }
 
     [Fact]
@@ -396,11 +397,264 @@ public async Task Set_FallbackModel_WritesCorrectRole()
 
         var config = ReadConfigFile(_paths.NetclawConfigPath);
         var models = config.RootElement.GetProperty("Models");
-        Assert.True(models.TryGetProperty("Main", out _)); // Main preserved
-        Assert.True(models.TryGetProperty("Fallback", out var fallback));
+        var roles = models.GetProperty("Roles");
+        Assert.True(roles.TryGetProperty("Main", out _)); // Main preserved
+        var fallback = ReadActiveModel(config, "Fallback");
         Assert.Equal("qwen3:8b", fallback.GetProperty("ModelId").GetString());
     }
 
+    [Fact]
+    public async Task Set_InputModalities_WritesOverrideWithoutProbing()
+    {
+        WriteConfig(ProvidersOnly());
+
+        // A non-OAuth provider never probes; --input-modalities is the manual override channel.
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b", "--input-modalities", "Text, Image"],
+            _paths, output: _output);
+
+        Assert.Equal(0, exitCode);
+        using var config = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(config, "Main");
+        Assert.Equal("Text, Image", main.GetProperty("InputModalities").GetString());
+    }
+
+    [Fact]
+    public async Task Set_ClearModalities_RemovesExistingOverride()
+    {
+        WriteConfig(WithMainModalities("Text, Image"));
+
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b", "--clear-modalities"],
+            _paths, output: _output);
+
+        Assert.Equal(0, exitCode);
+        using var config = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(config, "Main");
+        Assert.False(main.TryGetProperty("InputModalities", out _)); // cleared → runtime detection
+    }
+
+    [Theory]
+    [InlineData("invalid modalities", "--input-modalities", "Vision")]
+    [InlineData("--input-modalities requires a value", "--input-modalities")]
+    [InlineData("unknown argument '--input-modalites'", "--input-modalites", "Text")]
+    [InlineData("invalid modalities", "--input-modalities", "3")]
+    [InlineData("cannot be combined", "--context-window", "32768", "--clear-context-window")]
+    public async Task Set_InvalidOptions_ReturnErrorWithoutWriting(
+        string expectedError,
+        params string[] options)
+    {
+        WriteConfig(ProvidersOnly());
+
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b", .. options],
+            _paths, output: _output);
+
+        Assert.Equal(1, exitCode);
+        Assert.Contains(expectedError, _output.ToString());
+        Assert.False(ReadConfigFile(_paths.NetclawConfigPath).RootElement.TryGetProperty("Models", out _));
+    }
+
+    [Fact]
+    public async Task Set_SameModelReSetWithContextWindow_PreservesExistingModalities()
+    {
+        WriteConfig(WithMainModalities("Text, Image"));
+
+        // End-to-end: a --context-window-only re-set of the same model must keep the operator's
+        // modality override (#1127 / #5) — discovery/rebuild no longer wipes it.
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b", "--context-window", "65536"],
+            _paths, output: _output);
+
+        Assert.Equal(0, exitCode);
+        using var config = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(config, "Main");
+        Assert.Equal("Text, Image", main.GetProperty("InputModalities").GetString());
+        Assert.Equal(65536, main.GetProperty("ContextWindow").GetInt32());
+    }
+
+    [Fact]
+    public async Task Set_ClearContextWindow_RemovesStoredClamp()
+    {
+        var config = ProvidersOnly();
+        config["Models"] = new Dictionary<string, object>
+        {
+            ["Main"] = new Dictionary<string, object>
+            {
+                ["Provider"] = "my-ollama",
+                ["ModelId"] = "qwen3:30b",
+                ["ContextWindow"] = 32768
+            }
+        };
+        WriteConfig(config);
+
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b", "--clear-context-window"],
+            _paths, output: _output);
+
+        Assert.Equal(0, exitCode);
+        using var written = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(written, "Main");
+        Assert.False(main.TryGetProperty("ContextWindow", out _)); // clamp removed → runtime detection
+    }
+
+    [Fact]
+    public async Task Set_OAuthModelWithModalityOverride_StillProbesAndValidates()
+    {
+        WriteConfig(new Dictionary<string, object>
+        {
+            ["configVersion"] = 1,
+            ["Providers"] = new Dictionary<string, object>
+            {
+                ["openai-codex"] = new Dictionary<string, object>
+                {
+                    ["Type"] = "openai",
+                    ["AuthMethod"] = "OAuthDevice"
+                }
+            }
+        });
+        _fakeProbe.NextResult = new ProviderProbeResult(true, null,
+        [
+            new DiscoveredModel
+            {
+                ModelId = new Netclaw.Configuration.ModelId("gpt-new-codex"),
+                ContextWindowTokens = 512000,
+                InputModalities = ModelModality.Text | ModelModality.Image,
+                OutputModalities = ModelModality.Text,
+            }
+        ]);
+
+        // A modality override no longer short-circuits the probe: the probe must still run to
+        // validate the model and discover the context window, while the operator's modality wins.
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "openai-codex", "gpt-new-codex", "--input-modalities", "Text"],
+            _paths, _fakeProbe, output: _output);
+
+        Assert.Equal(0, exitCode);
+        Assert.Equal(1, _fakeProbe.ProbeCallCount);            // probe ran despite the modality flag
+        using var config = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(config, "Main");
+        Assert.Equal("Live", main.GetProperty("Provenance").GetString());     // resolved via probe
+        Assert.Equal(512000, main.GetProperty("ContextWindow").GetInt32());   // discovered window captured
+        Assert.Equal("Text", main.GetProperty("InputModalities").GetString());// operator override wins
+    }
+
+    [Fact]
+    public async Task Set_OAuthModelWithModalityOverride_WhenModelNotReturned_ReturnsError()
+    {
+        WriteConfig(new Dictionary<string, object>
+        {
+            ["configVersion"] = 1,
+            ["Providers"] = new Dictionary<string, object>
+            {
+                ["openai-codex"] = new Dictionary<string, object>
+                {
+                    ["Type"] = "openai",
+                    ["AuthMethod"] = "OAuthDevice"
+                }
+            }
+        });
+        _fakeProbe.NextResult = new ProviderProbeResult(true, null,
+        [
+            new DiscoveredModel { ModelId = new Netclaw.Configuration.ModelId("gpt-other-codex") }
+        ]);
+
+        // The modality flag must not let an unvalidated model slip through: the probe reports a
+        // different model, so the set must fail rather than write an unverified entry (#1610).
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "openai-codex", "gpt-new-codex", "--input-modalities", "Text"],
+            _paths, _fakeProbe, output: _output);
+
+        Assert.Equal(1, exitCode);
+        Assert.Contains("was not returned", _output.ToString());
+        Assert.False(ReadConfigFile(_paths.NetclawConfigPath).RootElement.TryGetProperty("Models", out _));
+    }
+
+    [Fact]
+    public async Task List_CorruptModalityConfig_ReturnsErrorWithoutCrashing()
+    {
+        // A config with an unparseable modality enum string must not crash `model list` with an
+        // unhandled JsonException, nor be silently reported as "no models configured" (#1610).
+        WriteConfig(WithMainEntry(new Dictionary<string, object>
+        {
+            ["Provider"] = "my-ollama",
+            ["ModelId"] = "qwen3:30b",
+            ["ContextWindow"] = 32768,
+            ["InputModalities"] = "text_and_image"
+        }));
+
+        var exitCode = await ModelCommand.RunAsync(["model", "list"], _paths, output: _output);
+
+        Assert.Equal(1, exitCode);
+        Assert.Contains("could not be parsed", _output.ToString());
+    }
+
+    [Fact]
+    public async Task Set_CorruptModalityButValidWindow_PreservesWindowEndToEnd()
+    {
+        // End-to-end regression for the full `model set` path: a re-set over a corrupt entry that
+        // has a VALID ContextWindow must succeed and keep the window (repairing the bad modality),
+        // not crash in the downgrade-check load path before reaching the writer (#1610).
+        WriteConfig(WithMainEntry(new Dictionary<string, object>
+        {
+            ["Provider"] = "my-ollama",
+            ["ModelId"] = "qwen3:30b",
+            ["ContextWindow"] = 32768,
+            ["InputModalities"] = "text_and_image"
+        }));
+
+        var exitCode = await ModelCommand.RunAsync(
+            ["model", "set", "main", "my-ollama", "qwen3:30b"], _paths, output: _output);
+
+        Assert.Equal(0, exitCode);
+        using var config = ReadConfigFile(_paths.NetclawConfigPath);
+        var main = ReadActiveModel(config, "Main");
+        Assert.Equal(32768, main.GetProperty("ContextWindow").GetInt32()); // valid clamp preserved
+        Assert.False(main.TryGetProperty("InputModalities", out _));        // corrupt override dropped
+    }
+
+    private static Dictionary<string, object> WithMainEntry(Dictionary<string, object> main)
+    {
+        var config = ProvidersOnly();
+        config["Models"] = new Dictionary<string, object> { ["Main"] = main };
+        return config;
+    }
+
+    private static JsonElement ReadActiveModel(JsonDocument config, string role)
+    {
+        var models = config.RootElement.GetProperty("Models");
+        var definitionName = models.GetProperty("Roles").GetProperty(role).GetString()!;
+        return models.GetProperty("Definitions").GetProperty(definitionName);
+    }
+
+    private static Dictionary<string, object> ProvidersOnly() => new()
+    {
+        ["configVersion"] = 1,
+        ["Providers"] = new Dictionary<string, object>
+        {
+            ["my-ollama"] = new Dictionary<string, object>
+            {
+                ["Type"] = "ollama",
+                ["Endpoint"] = "http://localhost:11434"
+            }
+        }
+    };
+
+    private static Dictionary<string, object> WithMainModalities(string inputModalities)
+    {
+        var config = ProvidersOnly();
+        config["Models"] = new Dictionary<string, object>
+        {
+            ["Main"] = new Dictionary<string, object>
+            {
+                ["Provider"] = "my-ollama",
+                ["ModelId"] = "qwen3:30b",
+                ["InputModalities"] = inputModalities
+            }
+        };
+        return config;
+    }
+
     private void WriteConfig(Dictionary<string, object> data)
     {
         File.WriteAllText(_paths.NetclawConfigPath,
diff --git a/src/Netclaw.Cli.Tests/Tui/ModelManagerViewModelTests.cs b/src/Netclaw.Cli.Tests/Tui/ModelManagerViewModelTests.cs
index 249954fb5..460d12dc0 100644
--- a/src/Netclaw.Cli.Tests/Tui/ModelManagerViewModelTests.cs
+++ b/src/Netclaw.Cli.Tests/Tui/ModelManagerViewModelTests.cs
@@ -159,7 +159,7 @@ public async Task ConfirmAssignment_WritesCorrectConfig()
 
         // Verify config
         var config = JsonDocument.Parse(File.ReadAllText(_paths.NetclawConfigPath));
-        var main = config.RootElement.GetProperty("Models").GetProperty("Main");
+        var main = ReadActiveModel(config, "Main");
         Assert.Equal("my-ollama", main.GetProperty("Provider").GetString());
         Assert.Equal("model-a", main.GetProperty("ModelId").GetString());
         Assert.Equal("Live", main.GetProperty("Provenance").GetString());
@@ -205,7 +205,7 @@ public async Task ConfirmAssignment_DiscoveredModelWithMetadata_WritesMetadata()
         vm.ConfirmAssignment();
 
         var config = JsonDocument.Parse(File.ReadAllText(_paths.NetclawConfigPath));
-        var main = config.RootElement.GetProperty("Models").GetProperty("Main");
+        var main = ReadActiveModel(config, "Main");
         Assert.Equal("Live", main.GetProperty("Provenance").GetString());
         Assert.Equal(512000, main.GetProperty("ContextWindow").GetInt32());
         Assert.Equal("Text, Image", main.GetProperty("InputModalities").GetString());
@@ -391,8 +391,9 @@ public void ClearRole_Fallback_RemovesFromConfig()
 
         var config = JsonDocument.Parse(File.ReadAllText(_paths.NetclawConfigPath));
         var models = config.RootElement.GetProperty("Models");
-        Assert.True(models.TryGetProperty("Main", out _));
-        Assert.False(models.TryGetProperty("Fallback", out _));
+        var roles = models.GetProperty("Roles");
+        Assert.True(roles.TryGetProperty("Main", out _));
+        Assert.False(roles.TryGetProperty("Fallback", out _));
     }
 
     [Fact]
@@ -497,11 +498,45 @@ public void Refresh_FallsBackToTypeWhenNoRegistry()
         Assert.Equal("ollama", vm.Providers[0].DisplayName);
     }
 
+    [Fact]
+    public void Refresh_MissingNamedDefinition_SurfacesInvalidConfiguration()
+    {
+        WriteConfig(new Dictionary<string, object>
+        {
+            ["configVersion"] = 1,
+            ["Models"] = new Dictionary<string, object>
+            {
+                ["Definitions"] = new Dictionary<string, object>
+                {
+                    ["known"] = new Dictionary<string, object>
+                    {
+                        ["Provider"] = "my-ollama",
+                        ["ModelId"] = "qwen3:30b"
+                    }
+                },
+                ["Roles"] = new Dictionary<string, object> { ["Main"] = "missing" }
+            }
+        });
+
+        using var vm = CreateViewModel();
+        vm.Refresh();
+
+        Assert.Null(vm.Models);
+        Assert.Contains("invalid", vm.StatusMessage.Value, StringComparison.OrdinalIgnoreCase);
+    }
+
     private ModelManagerViewModel CreateViewModel()
     {
         return new ModelManagerViewModel(_paths, _fakeProbe);
     }
 
+    private static JsonElement ReadActiveModel(JsonDocument config, string role)
+    {
+        var models = config.RootElement.GetProperty("Models");
+        var definitionName = models.GetProperty("Roles").GetProperty(role).GetString()!;
+        return models.GetProperty("Definitions").GetProperty(definitionName);
+    }
+
     private void WriteConfig(Dictionary<string, object> data)
     {
         File.WriteAllText(_paths.NetclawConfigPath,
diff --git a/src/Netclaw.Cli.Tests/Tui/Wizard/SectionEditorLeafTests.cs b/src/Netclaw.Cli.Tests/Tui/Wizard/SectionEditorLeafTests.cs
index 24643d279..ab8d25070 100644
--- a/src/Netclaw.Cli.Tests/Tui/Wizard/SectionEditorLeafTests.cs
+++ b/src/Netclaw.Cli.Tests/Tui/Wizard/SectionEditorLeafTests.cs
@@ -29,6 +29,8 @@ public void BuildContribution_EnteredCredential_EmitsSensitiveSecretLeaf()
         Assert.Equal(SectionSecretActionKind.Set, action.Action);
         Assert.NotNull(action.Value);
         Assert.Equal("sk-test", action.Value.Value);
+        Assert.DoesNotContain(contribution.FieldActionsOrEmpty, field =>
+            field.Path.StartsWith("Models", StringComparison.Ordinal));
     }
 
     [Fact]
diff --git a/src/Netclaw.Cli.Tests/Tui/Wizard/WizardConfigBuilderTests.cs b/src/Netclaw.Cli.Tests/Tui/Wizard/WizardConfigBuilderTests.cs
index eb7d3cb94..d02f56f42 100644
--- a/src/Netclaw.Cli.Tests/Tui/Wizard/WizardConfigBuilderTests.cs
+++ b/src/Netclaw.Cli.Tests/Tui/Wizard/WizardConfigBuilderTests.cs
@@ -83,7 +83,9 @@ public void BuildConfigDictionary_IncludesModelsSection()
         var config = builder.BuildConfigDictionary();
 
         var models = (Dictionary<string, object>)config["Models"];
-        var main = (Dictionary<string, object>)models["Main"];
+        var roles = (Dictionary<string, object>)models["Roles"];
+        var definitions = (Dictionary<string, object>)models["Definitions"];
+        var main = (Dictionary<string, object>)definitions[(string)roles["Main"]];
         Assert.Equal("openai", main["Provider"]);
         Assert.Equal("gpt-4.1", main["ModelId"]);
     }
diff --git a/src/Netclaw.Cli/Config/ConfigFileHelper.cs b/src/Netclaw.Cli/Config/ConfigFileHelper.cs
index a3079917f..2fd3f3fed 100644
--- a/src/Netclaw.Cli/Config/ConfigFileHelper.cs
+++ b/src/Netclaw.Cli/Config/ConfigFileHelper.cs
@@ -159,7 +159,37 @@ internal static Dictionary<string, object> GetOrCreateSection(
     /// Serialize a config dictionary and write it to disk, creating parent directories if needed.
     /// </summary>
     internal static void WriteConfigFile(string path, Dictionary<string, object> data)
-        => AtomicFile.WriteAllText(path, JsonSerializer.Serialize(data, JsonDefaults.ConfigFile));
+    {
+        PreserveLegacyModelsBackup(path, data);
+        AtomicFile.WriteAllText(path, JsonSerializer.Serialize(data, JsonDefaults.ConfigFile));
+    }
+
+    private static void PreserveLegacyModelsBackup(string path, Dictionary<string, object> data)
+    {
+        if (!File.Exists(path)
+            || GetSectionOrNull(data, "Models") is not { } newModels
+            || !newModels.ContainsKey("Definitions"))
+            return;
+
+        using var existing = JsonDocument.Parse(File.ReadAllText(path));
+        if (!existing.RootElement.TryGetProperty("Models", out var oldModels)
+            || oldModels.ValueKind != JsonValueKind.Object
+            || !oldModels.TryGetProperty("Main", out _))
+            return;
+
+        var legacyEnvironmentOverride = ModelEntryWriter.FindLegacyEnvironmentOverride();
+        if (legacyEnvironmentOverride is not null)
+        {
+            throw new InvalidOperationException(
+                $"Cannot migrate Models while legacy environment override '{legacyEnvironmentOverride}' is set. " +
+                "Move model overrides to NETCLAW_Models__Definitions__<name>__* and " +
+                "NETCLAW_Models__Roles__* first.");
+        }
+
+        var backupPath = path + ".legacy-models.bak";
+        if (!File.Exists(backupPath))
+            File.Copy(path, backupPath);
+    }
 
     /// <summary>
     /// Serialize and write secrets.json using hardened permissions and encryption-at-rest.
diff --git a/src/Netclaw.Cli/Config/ModelEntryWriter.cs b/src/Netclaw.Cli/Config/ModelEntryWriter.cs
index dd0a22560..0c3f7e697 100644
--- a/src/Netclaw.Cli/Config/ModelEntryWriter.cs
+++ b/src/Netclaw.Cli/Config/ModelEntryWriter.cs
@@ -3,6 +3,8 @@
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
 // -----------------------------------------------------------------------
+using System.Text.Json;
+using Netclaw.Cli.Json;
 using Netclaw.Configuration;
 
 namespace Netclaw.Cli.Config;
@@ -16,6 +18,434 @@ namespace Netclaw.Cli.Config;
 /// </summary>
 internal static class ModelEntryWriter
 {
+    private static readonly string[] LegacyEnvironmentPrefixes =
+    [
+        "NETCLAW_Models__Main__",
+        "NETCLAW_Models__Fallback__",
+        "NETCLAW_Models__Compaction__",
+    ];
+
+    internal static string? FindLegacyEnvironmentOverride()
+        => Environment.GetEnvironmentVariables().Keys
+            .OfType<string>()
+            .FirstOrDefault(key => LegacyEnvironmentPrefixes.Any(prefix =>
+                key.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)));
+
+    internal static bool MigrateLegacy(Dictionary<string, object> modelsSection)
+    {
+        if (modelsSection.ContainsKey("Definitions") || modelsSection.ContainsKey("Roles"))
+            return false;
+        if (!modelsSection.Keys.Any(key => key is "Main" or "Fallback" or "Compaction"))
+            return false;
+        EnsureNamedShape(modelsSection);
+        return true;
+    }
+
+    internal static bool ClearRole(Dictionary<string, object> modelsSection, string roleKey)
+    {
+        var (_, roles) = EnsureNamedShape(modelsSection);
+        return roles.Remove(roleKey);
+    }
+
+    /// <summary>
+    /// Write a role's model entry into <paramref name="modelsSection"/> non-destructively.
+    /// Two on-disk attributes are treated as operator-owned overrides that provider discovery
+    /// must never silently clobber on a same-<c>(provider, modelId)</c> re-set:
+    /// <list type="bullet">
+    /// <item><description>
+    /// <c>ContextWindow</c> and the modalities are documented to "take precedence over
+    /// provider-reported capability detection". So the precedence for each is:
+    /// explicit operator input (this call) &gt; existing stored value &gt; probe. A fresh probe
+    /// tops up a first-time set or a model switch, but never overwrites a value already on disk
+    /// — that overwrite was the #1127 loss (a re-set wiped a hand-set modality) and its
+    /// context-window twin (#1610).
+    /// </description></item>
+    /// </list>
+    /// Because the stored value now wins, the operator needs a way to *change* it: an explicit
+    /// <see cref="ValueOverride{T}.Set"/> replaces it and <see cref="ValueOverride{T}.Clear"/>
+    /// removes it (falling back to runtime detection). Switching a role to a <em>different</em>
+    /// model does not carry the old model's attributes over — they belonged to that model.
+    /// </summary>
+    /// <param name="contextWindow">
+    /// Operator intent for the context window (set / clear / unset). <c>--context-window</c> sets
+    /// it (wins over everything), <c>--clear-context-window</c> removes the clamp so detection
+    /// resolves it, and the picker — which has no such input — passes <see cref="ValueOverride{T}.Unset"/>.
+    /// </param>
+    /// <param name="inputModalities">Operator intent for input modalities (set / clear / unset).</param>
+    /// <param name="outputModalities">Operator intent for output modalities (set / clear / unset).</param>
+    /// <param name="discovered">
+    /// The probe result, if a probe ran. Its context window and modalities seed a first-time set
+    /// or a model switch only; an existing stored value wins over them.
+    /// </param>
+    internal static void WriteRole(
+        Dictionary<string, object> modelsSection,
+        string roleKey,
+        string provider,
+        string? modelId,
+        ModelDiscoverySource? provenance,
+        ValueOverride<int> contextWindow,
+        ValueOverride<ModelModality> inputModalities,
+        ValueOverride<ModelModality> outputModalities,
+        DiscoveredModel? discovered)
+    {
+        var (definitions, roles) = EnsureNamedShape(modelsSection, roleKey);
+        var definitionName = FindDefinition(definitions, provider, modelId)
+                             ?? CreateDefinitionName(definitions, provider, modelId);
+        var existing = ReadSameModelEntry(definitions, definitionName, provider, modelId);
+
+        // Provenance records how the model ID was resolved, not how the entry was last edited. A
+        // same-model re-set that did not itself freshly resolve the ID — no probe (the caller
+        // passes Manual) or a probe that failed (Defaults) — must not downgrade a previously
+        // discovered origin. Only a fresh successful discovery (Live) re-stamps it (#1610).
+        if (existing?.Provenance is { } priorProvenance && provenance != ModelDiscoverySource.Live)
+            provenance = priorProvenance;
+
+        // Precedence for every operator-owned attribute: explicit input > existing stored value
+        // > probe. Collapsing the explicit and discovered values in the caller defeated
+        // preservation, because the probe/picker paths always pass a discovered value, so the
+        // stored value was overwritten on every re-selection.
+        var sameModelEntry = existing is not null;
+        var resolvedWindow = ResolveContextWindow(
+            contextWindow, sameModelEntry, existing?.ContextWindow, discovered?.ContextWindowTokens);
+        var resolvedInput = ResolveModality(inputModalities, sameModelEntry, existing?.InputModalities, discovered?.InputModalities);
+        var resolvedOutput = ResolveModality(outputModalities, sameModelEntry, existing?.OutputModalities, discovered?.OutputModalities);
+
+        definitions[definitionName] = BuildModelEntry(
+            provider, modelId, provenance, resolvedWindow, resolvedInput, resolvedOutput);
+        roles[roleKey] = definitionName;
+    }
+
+    private static (Dictionary<string, object> Definitions, Dictionary<string, object> Roles)
+        EnsureNamedShape(Dictionary<string, object> modelsSection, string? overwrittenRole = null)
+    {
+        var hasNamed = modelsSection.ContainsKey("Definitions") || modelsSection.ContainsKey("Roles");
+        var hasLegacy = modelsSection.Keys.Any(key =>
+            key is "Main" or "Fallback" or "Compaction");
+
+        if (hasNamed && hasLegacy)
+            throw new InvalidOperationException("Models configuration mixes legacy roles with Definitions/Roles.");
+
+        if (hasNamed)
+        {
+            if (!modelsSection.ContainsKey("Definitions") || !modelsSection.ContainsKey("Roles"))
+                throw new InvalidOperationException("Named Models configuration requires Definitions and Roles.");
+
+            return (GetDictionary(modelsSection, "Definitions"), GetDictionary(modelsSection, "Roles"));
+        }
+
+        var definitions = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
+        var roles = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var role in new[] { "Main", "Fallback", "Compaction" })
+        {
+            if (!modelsSection.TryGetValue(role, out var raw) || raw is null)
+                continue;
+
+            if (!RawContainsProperty(raw, nameof(ModelReference.Provider))
+                || !RawContainsProperty(raw, nameof(ModelReference.ModelId)))
+            {
+                if (string.Equals(role, overwrittenRole, StringComparison.OrdinalIgnoreCase))
+                    continue;
+                throw new InvalidOperationException(
+                    $"Models:{role} must explicitly declare Provider and ModelId before migration.");
+            }
+
+            ModelReference model;
+            try
+            {
+                model = ConfigFileHelper.DeserializeSection<ModelReference>(raw)
+                        ?? throw new InvalidOperationException($"Models:{role} could not be parsed.");
+            }
+            catch (JsonException)
+            {
+                model = ReadLegacyIdentity(raw)
+                        ?? throw new InvalidOperationException($"Models:{role} could not be repaired.");
+            }
+            var existingName = FindDefinition(definitions, model.Provider, model.ModelId);
+            if (existingName is not null)
+            {
+                var existing = ConfigFileHelper.DeserializeSection<ModelReference>(definitions[existingName])!;
+                if (!Equivalent(existing, model))
+                {
+                    throw new InvalidOperationException(
+                        $"Legacy model roles conflict for {model.Provider}/{model.ModelId}; " +
+                        $"align their metadata before migration.");
+                }
+
+                roles[role] = existingName;
+                continue;
+            }
+
+            var name = CreateDefinitionName(definitions, model.Provider, model.ModelId);
+            definitions[name] = BuildModelEntry(
+                model.Provider, model.ModelId, model.Provenance, model.ContextWindow,
+                model.InputModalities, model.OutputModalities);
+            roles[role] = name;
+        }
+
+        modelsSection.Clear();
+        modelsSection["Definitions"] = definitions;
+        modelsSection["Roles"] = roles;
+        return (definitions, roles);
+    }
+
+    private static ModelReference? ReadLegacyIdentity(object raw)
+    {
+        var json = raw is JsonElement element
+            ? element.GetRawText()
+            : JsonSerializer.Serialize(raw, JsonDefaults.ConfigFile);
+        using var document = JsonDocument.Parse(json);
+        var root = document.RootElement;
+        if (root.ValueKind != JsonValueKind.Object
+            || !TryGetString(root, nameof(ModelReference.Provider), out var provider)
+            || !TryGetString(root, nameof(ModelReference.ModelId), out var modelId))
+            return null;
+
+        var model = new ModelReference { Provider = provider, ModelId = modelId };
+        if (TryGetInt32(root, nameof(ModelReference.ContextWindow), out var contextWindow))
+            model.ContextWindow = contextWindow;
+        return model;
+    }
+
+    private static Dictionary<string, object> GetDictionary(Dictionary<string, object> parent, string key)
+    {
+        var raw = parent[key];
+        if (raw is Dictionary<string, object> dictionary)
+            return dictionary;
+        if (raw is JsonElement { ValueKind: JsonValueKind.Object } element)
+        {
+            dictionary = JsonSerializer.Deserialize<Dictionary<string, object>>(element.GetRawText()) ?? [];
+            parent[key] = dictionary;
+            return dictionary;
+        }
+
+        throw new InvalidOperationException($"Models:{key} must be an object.");
+    }
+
+    private static string? FindDefinition(
+        Dictionary<string, object> definitions, string provider, string? modelId)
+    {
+        foreach (var (name, raw) in definitions)
+        {
+            ModelReference? model;
+            try
+            {
+                model = ConfigFileHelper.DeserializeSection<ModelReference>(raw);
+            }
+            catch (JsonException)
+            {
+                model = ReadLegacyIdentity(raw);
+            }
+
+            if (model is not null
+                && string.Equals(model.Provider, provider, StringComparison.OrdinalIgnoreCase)
+                && string.Equals(model.ModelId, modelId, StringComparison.OrdinalIgnoreCase))
+                return name;
+        }
+
+        return null;
+    }
+
+    private static string CreateDefinitionName(
+        Dictionary<string, object> definitions, string provider, string? modelId)
+    {
+        var raw = $"{provider}-{modelId}";
+        var stem = string.Join('-', raw.ToLowerInvariant()
+            .Split(['/', ':', '.', '_', ' '], StringSplitOptions.RemoveEmptyEntries))
+            .Trim('-');
+        if (string.IsNullOrWhiteSpace(stem))
+            stem = "model";
+
+        var candidate = stem;
+        for (var suffix = 2; definitions.ContainsKey(candidate); suffix++)
+            candidate = $"{stem}-{suffix}";
+        return candidate;
+    }
+
+    private static bool Equivalent(ModelReference left, ModelReference right)
+        => string.Equals(left.Provider, right.Provider, StringComparison.OrdinalIgnoreCase)
+           && string.Equals(left.ModelId, right.ModelId, StringComparison.OrdinalIgnoreCase)
+           && left.ContextWindow == right.ContextWindow
+           && left.Provenance == right.Provenance
+           && left.InputModalities == right.InputModalities
+           && left.OutputModalities == right.OutputModalities;
+
+    /// <summary>
+    /// Resolves the modality actually written. An explicit operator set or clear wins outright
+    /// (the operator is the authority on a manual override). Otherwise, when the same model already
+    /// has an entry on disk, that entry is honored verbatim — including a deliberately-cleared
+    /// (absent) modality, so a later probe cannot silently resurrect an override the operator
+    /// removed with <c>--clear-modalities</c> (#1610). Provider discovery only seeds a genuine gap:
+    /// a first-time set or a switch to a different model, where no entry exists yet.
+    /// </summary>
+    private static ModelModality? ResolveModality(
+        ValueOverride<ModelModality> @override, bool sameModelEntryExists,
+        ModelModality? existing, ModelModality? discovered)
+        => @override.Supplied
+            ? @override.Value                 // Set(value) → value; Clear → null (key omitted downstream)
+            : sameModelEntryExists ? existing  // same model on disk: honor it, incl. a cleared (null) value
+                : discovered;                  // first set / model switch: seed from discovery
+
+    /// <summary>
+    /// Resolves the context window actually written. Mirrors <see cref="ResolveModality"/> for the
+    /// explicit cases: <c>--context-window</c> (Set) or <c>--clear-context-window</c> (Clear) wins,
+    /// otherwise an existing definition is honored verbatim, including absence. Discovery seeds
+    /// only a new definition. This keeps manual JSON edits and explicit clears stable without a
+    /// hidden tombstone representation.
+    /// </summary>
+    private static int? ResolveContextWindow(
+        ValueOverride<int> @override, bool sameModelEntryExists, int? existing, int? discovered)
+        => @override.Supplied
+            ? @override.Value            // Set(n) → n; Clear → null (drop the clamp → runtime detects)
+            : sameModelEntryExists ? existing : discovered;
+
+    /// <summary>
+    /// The role's current entry, but only when it already references the same
+    /// <c>(provider, modelId)</c>; null when the role is unset or points at a different
+    /// model (whose attributes must not carry over to the newly-set one).
+    /// </summary>
+    private static ModelReference? ReadSameModelEntry(
+        Dictionary<string, object> modelsSection, string roleKey, string provider, string? modelId)
+    {
+        if (!modelsSection.TryGetValue(roleKey, out var raw) || raw is null)
+            return null;
+
+        // ModelReference defaults Provider/ModelId to the stock local-ollama model, so an
+        // entry that OMITS either key deserializes to that default and would false-match a
+        // re-set of the stock model — carrying stray attributes onto a model the entry never
+        // actually named. Only treat the entry as the same model when it explicitly declares
+        // both keys (#1610).
+        if (!RawContainsProperty(raw, nameof(ModelReference.Provider))
+            || !RawContainsProperty(raw, nameof(ModelReference.ModelId)))
+            return null;
+
+        // A legacy or hand-corrupted entry (e.g. an unrecognized modality enum string, or a
+        // shape that predates a schema change) must not abort `model set`: we are about to
+        // overwrite this role anyway, and before the non-destructive rewrite existed the
+        // command simply clobbered it.
+        ModelReference? existing;
+        try
+        {
+            existing = ConfigFileHelper.DeserializeSection<ModelReference>(raw);
+        }
+        catch (JsonException)
+        {
+            // Strict deserialization failed — in practice a stale/unknown modality or provenance
+            // enum string, which JsonStringEnumConverter rejects by throwing. Discarding the whole
+            // entry here would silently clobber a still-valid operator-owned ContextWindow (#1610),
+            // so recover the throw-proof fields and drop only the unparseable overrides.
+            return ReadResilient(raw, provider, modelId);
+        }
+
+        if (existing is null)
+            return null;
+
+        return string.Equals(existing.Provider, provider, StringComparison.OrdinalIgnoreCase)
+            && string.Equals(existing.ModelId, modelId, StringComparison.OrdinalIgnoreCase)
+            ? existing
+            : null;
+    }
+
+    /// <summary>
+    /// Recovers the preservation-worthy fields from an entry that failed strict deserialization.
+    /// Provider, ModelId and ContextWindow are plain strings/int that never throw, so they are read
+    /// directly; the modality/provenance overrides — the fields that failed to parse — are dropped
+    /// (left null) because a value we could not read must not be preserved. Returns null when the
+    /// recovered entry names a different model (its attributes must not carry over) or is not a
+    /// JSON object.
+    /// </summary>
+    private static ModelReference? ReadResilient(object raw, string provider, string? modelId)
+    {
+        var json = raw is JsonElement element
+            ? element.GetRawText()
+            : JsonSerializer.Serialize(raw, JsonDefaults.ConfigFile);
+
+        using var doc = JsonDocument.Parse(json);
+        var root = doc.RootElement;
+        if (root.ValueKind != JsonValueKind.Object)
+            return null;
+
+        // Confirm the poisoned entry still names the model being set before preserving anything.
+        if (!TryGetString(root, nameof(ModelReference.Provider), out var storedProvider)
+            || !TryGetString(root, nameof(ModelReference.ModelId), out var storedModelId)
+            || !string.Equals(storedProvider, provider, StringComparison.OrdinalIgnoreCase)
+            || !string.Equals(storedModelId, modelId, StringComparison.OrdinalIgnoreCase))
+            return null;
+
+        var recovered = new ModelReference { Provider = storedProvider, ModelId = storedModelId };
+        if (TryGetInt32(root, nameof(ModelReference.ContextWindow), out var window))
+            recovered.ContextWindow = window;
+
+        return recovered;
+    }
+
+    private static bool TryGetString(JsonElement root, string name, out string value)
+    {
+        foreach (var property in root.EnumerateObject())
+        {
+            if (string.Equals(property.Name, name, StringComparison.OrdinalIgnoreCase)
+                && property.Value.ValueKind == JsonValueKind.String)
+            {
+                value = property.Value.GetString()!;
+                return true;
+            }
+        }
+
+        value = string.Empty;
+        return false;
+    }
+
+    private static bool TryGetInt32(JsonElement root, string name, out int value)
+    {
+        foreach (var property in root.EnumerateObject())
+        {
+            if (!string.Equals(property.Name, name, StringComparison.OrdinalIgnoreCase))
+                continue;
+
+            // Web-default reads coerce numeric strings, so accept both a JSON number and a
+            // stringified integer to match what the strict path would have parsed.
+            if (property.Value.ValueKind == JsonValueKind.Number && property.Value.TryGetInt32(out value))
+                return true;
+            if (property.Value.ValueKind == JsonValueKind.String
+                && int.TryParse(property.Value.GetString(), out value))
+                return true;
+        }
+
+        value = 0;
+        return false;
+    }
+
+    /// <summary>
+    /// Whether the raw config value explicitly declares <paramref name="propertyName"/>. The
+    /// value is either a <see cref="JsonElement"/> (loaded from disk) or an in-memory
+    /// dictionary (rewritten this run) — the two shapes <see cref="ConfigFileHelper.DeserializeSection{T}"/>
+    /// accepts. The match is case-insensitive to mirror the case-insensitive deserialization.
+    /// </summary>
+    private static bool RawContainsProperty(object raw, string propertyName)
+    {
+        switch (raw)
+        {
+            case JsonElement { ValueKind: JsonValueKind.Object } element:
+                foreach (var property in element.EnumerateObject())
+                {
+                    if (string.Equals(property.Name, propertyName, StringComparison.OrdinalIgnoreCase))
+                        return true;
+                }
+
+                return false;
+            case IDictionary<string, object> dict:
+                foreach (var key in dict.Keys)
+                {
+                    if (string.Equals(key, propertyName, StringComparison.OrdinalIgnoreCase))
+                        return true;
+                }
+
+                return false;
+            default:
+                return false;
+        }
+    }
+
     /// <summary>
     /// Builds the dictionary written under <c>Models[role]</c>.
     /// </summary>
@@ -55,3 +485,25 @@ internal static Dictionary<string, object> BuildModelEntry(
         return entry;
     }
 }
+
+/// <summary>
+/// An operator's intent for an overridable, operator-owned model attribute on <c>model set</c> —
+/// a modality set (<see cref="ModelModality"/>) or the context window (<see cref="int"/>). A plain
+/// <c>T?</c> cannot express it, because two of the three states both resolve to null yet behave
+/// oppositely: "not supplied" must preserve any existing override, while "clear" must win over it.
+/// The tri-state is: <see cref="Unset"/> (leave it to the stored value / discovery),
+/// <see cref="Set"/> (replace with an explicit value), and <see cref="Clear"/> (remove the override
+/// so runtime detection resolves it).
+/// </summary>
+internal readonly record struct ValueOverride<T>(bool Supplied, T? Value)
+    where T : struct
+{
+    /// <summary>Operator said nothing — preserve the stored value, else fall back to discovery.</summary>
+    internal static ValueOverride<T> Unset => default;
+
+    /// <summary>Operator asked to remove the override so runtime capability detection resolves it.</summary>
+    internal static ValueOverride<T> Clear => new(true, null);
+
+    /// <summary>Operator supplied an explicit value that replaces whatever is stored.</summary>
+    internal static ValueOverride<T> Set(T value) => new(true, value);
+}
diff --git a/src/Netclaw.Cli/Doctor/ChatClientDoctorCheck.cs b/src/Netclaw.Cli/Doctor/ChatClientDoctorCheck.cs
index 9f07bd2e8..492ed76c6 100644
--- a/src/Netclaw.Cli/Doctor/ChatClientDoctorCheck.cs
+++ b/src/Netclaw.Cli/Doctor/ChatClientDoctorCheck.cs
@@ -61,7 +61,7 @@ public Task<DoctorCheckResult> RunAsync(CancellationToken cancellationToken = de
         try
         {
             providers = ProviderConfigurationLoader.Load(_configuration.GetSection("Providers"));
-            models = _configuration.GetSection("Models").Get<ModelSelection>() ?? new ModelSelection();
+            models = ModelConfigurationResolver.Resolve(_configuration).Selection;
             // File present: read explicit provider types from the file (matches
             // historical behavior). Env-only: derive them from the bound
             // configuration, exactly like the daemon does at startup.
diff --git a/src/Netclaw.Cli/Doctor/ContextWindowDoctorCheck.cs b/src/Netclaw.Cli/Doctor/ContextWindowDoctorCheck.cs
index b88770310..d68bfe68c 100644
--- a/src/Netclaw.Cli/Doctor/ContextWindowDoctorCheck.cs
+++ b/src/Netclaw.Cli/Doctor/ContextWindowDoctorCheck.cs
@@ -43,8 +43,8 @@ public async Task<DoctorCheckResult> RunAsync(CancellationToken cancellationToke
         if (root is null)
             return DoctorCheckResult.Pass("Context Window", "No config file to check.");
 
-        var models = root["Models"] as JsonObject;
-        var main = models?["Main"] as JsonObject;
+        var resolvedModels = ModelConfigurationResolver.Resolve(_configuration).Selection;
+        var main = resolvedModels.Main;
 
         var runtimeValidation = ValidateRuntimeConfiguration(root);
         if (runtimeValidation.Status != ProviderRuntimeStatus.Valid)
@@ -55,7 +55,7 @@ public async Task<DoctorCheckResult> RunAsync(CancellationToken cancellationToke
                 BuildInferenceRemediation(runtimeValidation.AvailableProviders));
         }
 
-        if (main is null)
+        if (string.IsNullOrWhiteSpace(main.Provider) || string.IsNullOrWhiteSpace(main.ModelId))
         {
             return DoctorCheckResult.Warning(
                 "Context Window",
@@ -63,15 +63,12 @@ public async Task<DoctorCheckResult> RunAsync(CancellationToken cancellationToke
                 "Run `netclaw init` to configure a provider and main model, or add Models.Main to netclaw.json.");
         }
 
-        var contextWindow = main["ContextWindow"];
-        if (contextWindow is null)
+        if (main.ContextWindow is null)
         {
-            var modelId = _configuration.GetSection("Models:Main:ModelId").Value ?? "unknown";
-            var providerName = _configuration.GetSection("Models:Main:Provider").Value ?? "unknown";
-            return await ResolveEffectiveContextWindowAsync(modelId, providerName, cancellationToken);
+            return await ResolveEffectiveContextWindowAsync(main.ModelId, main.Provider, cancellationToken);
         }
 
-        if (TryGetInt32(contextWindow, out var cw) && cw > 0)
+        if (main.ContextWindow is > 0 and var cw)
         {
             // Runtime (ContextWindowResolution.ResolveRuntimeAsync) prefers the
             // daemon's live context window over the pinned config when the daemon
@@ -100,8 +97,7 @@ public async Task<DoctorCheckResult> RunAsync(CancellationToken cancellationToke
     private ProviderRuntimeValidation ValidateRuntimeConfiguration(JsonObject root)
     {
         var providers = ProviderConfigurationLoader.Load(_configuration.GetSection("Providers"));
-        var models = _configuration.GetSection("Models")
-            .Get<ModelSelection>() ?? new ModelSelection();
+        var models = ModelConfigurationResolver.Resolve(_configuration).Selection;
 
         return ProviderRuntimeValidation.Evaluate(
             providers,
diff --git a/src/Netclaw.Cli/Doctor/DoctorFixService.cs b/src/Netclaw.Cli/Doctor/DoctorFixService.cs
index c77225c88..57e5e19ce 100644
--- a/src/Netclaw.Cli/Doctor/DoctorFixService.cs
+++ b/src/Netclaw.Cli/Doctor/DoctorFixService.cs
@@ -4,6 +4,7 @@
 // </copyright>
 // -----------------------------------------------------------------------
 using System.Text.Json.Nodes;
+using System.Text.Json;
 using Json.Schema;
 using Netclaw.Cli.Config;
 using Netclaw.Cli.Daemon;
@@ -64,6 +65,25 @@ public Task<DoctorFixPlan> BuildPlanAsync(CancellationToken cancellationToken =
 
         var appliedFixes = new List<string>();
 
+        if (obj["Models"] is JsonObject modelsNode)
+        {
+            var legacyEnvironmentOverride = ModelEntryWriter.FindLegacyEnvironmentOverride();
+            if (legacyEnvironmentOverride is not null)
+            {
+                throw new InvalidOperationException(
+                    $"Cannot migrate Models while legacy environment override '{legacyEnvironmentOverride}' is set. " +
+                    "Move model overrides to NETCLAW_Models__Definitions__<name>__* and " +
+                    "NETCLAW_Models__Roles__* first.");
+            }
+
+            var models = JsonSerializer.Deserialize<Dictionary<string, object>>(modelsNode.ToJsonString())!;
+            if (ModelEntryWriter.MigrateLegacy(models))
+            {
+                obj["Models"] = JsonNode.Parse(JsonSerializer.Serialize(models, JsonDefaults.ConfigFile));
+                appliedFixes.Add("named model definitions");
+            }
+        }
+
         // --- Manual fixes (not derivable from schema alone) ---
 
         if (obj["configVersion"] is null)
@@ -256,7 +276,7 @@ private void TryAddDaemonPathEnvironmentFix(List<DoctorFileFix> fixes)
             UpdatedText: updated));
     }
 
-    public async Task ApplyAsync(DoctorFixPlan plan, CancellationToken cancellationToken = default)
+    public Task ApplyAsync(DoctorFixPlan plan, CancellationToken cancellationToken = default)
     {
         foreach (var fix in plan.Fixes)
         {
@@ -267,8 +287,19 @@ public async Task ApplyAsync(DoctorFixPlan plan, CancellationToken cancellationT
             if (!string.IsNullOrEmpty(dir))
                 Directory.CreateDirectory(dir);
 
-            await File.WriteAllTextAsync(fix.FilePath, fix.UpdatedText, cancellationToken);
+            cancellationToken.ThrowIfCancellationRequested();
+            if (fix.Description.Contains("named model definitions", StringComparison.Ordinal)
+                && File.Exists(fix.FilePath))
+            {
+                var backupPath = fix.FilePath + ".legacy-models.bak";
+                if (!File.Exists(backupPath))
+                    File.Copy(fix.FilePath, backupPath);
+            }
+
+            AtomicFile.WriteAllText(fix.FilePath, fix.UpdatedText);
         }
+
+        return Task.CompletedTask;
     }
 
 }
diff --git a/src/Netclaw.Cli/Model/ModelCommand.cs b/src/Netclaw.Cli/Model/ModelCommand.cs
index 768b13efa..44021cc61 100644
--- a/src/Netclaw.Cli/Model/ModelCommand.cs
+++ b/src/Netclaw.Cli/Model/ModelCommand.cs
@@ -4,6 +4,7 @@
 // </copyright>
 // -----------------------------------------------------------------------
 using System.Text.Json;
+using Microsoft.Extensions.Configuration;
 using Netclaw.Cli.Config;
 using Netclaw.Cli.Json;
 using Netclaw.Cli.Provider;
@@ -37,7 +38,15 @@ public static async Task<int> RunAsync(
 
     private static int RunList(NetclawPaths paths, TextWriter writer)
     {
-        var models = LoadModelSelection(paths);
+        if (!TryLoadModelSelection(paths, out var models))
+        {
+            // Config present but unparseable — surface it rather than showing a corrupt config as
+            // "no models configured", which would send the operator down the wrong recovery path.
+            writer.WriteLine("Error: model configuration could not be parsed.");
+            writer.WriteLine("Run `netclaw doctor` to diagnose, or `netclaw doctor --fix` to repair it.");
+            return 1;
+        }
+
         if (models is null)
         {
             writer.WriteLine("No models configured.");
@@ -73,10 +82,13 @@ private static void WriteModelRow(string role, ModelReference model, TextWriter
     private static async Task<int> RunSetAsync(
         string[] args, NetclawPaths paths, IProviderProbe? probe, TextWriter writer)
     {
-        // Parse: netclaw model set <role> <provider> <model-id> [--context-window <tokens>]
+        // Parse: netclaw model set <role> <provider> <model-id>
+        //        [--context-window <tokens>] [--input-modalities <list>]
+        //        [--output-modalities <list>] [--clear-modalities]
         if (args.Length < 5)
         {
-            writer.WriteLine("Usage: netclaw model set <role> <provider> <model-id> [--context-window <tokens>]");
+            writer.WriteLine("Usage: netclaw model set <role> <provider> <model-id> [--context-window <tokens>] [--clear-context-window]");
+            writer.WriteLine("                       [--input-modalities <list>] [--output-modalities <list>] [--clear-modalities]");
             writer.WriteLine();
             writer.WriteLine("Roles: main, fallback, compaction");
             return 1;
@@ -86,21 +98,96 @@ private static async Task<int> RunSetAsync(
         var providerName = args[3];
         var modelId = args[4];
         int? contextWindow = null;
+        var clearContextWindow = false;
+        ModelModality? inputModalitySet = null;
+        ModelModality? outputModalitySet = null;
+        var clearModalities = false;
 
         for (var i = 5; i < args.Length; i++)
         {
-            if (args[i] is "--context-window" && i + 1 < args.Length)
+            switch (args[i])
             {
-                if (!int.TryParse(args[++i], out var cw) || cw <= 0)
-                {
-                    writer.WriteLine("Error: --context-window must be a positive integer.");
+                case "--context-window":
+                    if (!TryTakeValue(args, ref i, out var cwRaw))
+                    {
+                        writer.WriteLine("Error: --context-window requires a value.");
+                        return 1;
+                    }
+
+                    if (!int.TryParse(cwRaw, out var cw) || cw <= 0)
+                    {
+                        writer.WriteLine("Error: --context-window must be a positive integer.");
+                        return 1;
+                    }
+
+                    contextWindow = cw;
+                    break;
+                case "--clear-context-window":
+                    clearContextWindow = true;
+                    break;
+                case "--input-modalities":
+                    if (!TryTakeValue(args, ref i, out var inputRaw))
+                    {
+                        writer.WriteLine("Error: --input-modalities requires a value.");
+                        return 1;
+                    }
+
+                    if (!TryParseModalities(inputRaw, out var input, out var inputError))
+                    {
+                        writer.WriteLine(inputError);
+                        return 1;
+                    }
+
+                    inputModalitySet = input;
+                    break;
+                case "--output-modalities":
+                    if (!TryTakeValue(args, ref i, out var outputRaw))
+                    {
+                        writer.WriteLine("Error: --output-modalities requires a value.");
+                        return 1;
+                    }
+
+                    if (!TryParseModalities(outputRaw, out var outputModality, out var outputError))
+                    {
+                        writer.WriteLine(outputError);
+                        return 1;
+                    }
+
+                    outputModalitySet = outputModality;
+                    break;
+                case "--clear-modalities":
+                    clearModalities = true;
+                    break;
+                default:
+                    // Fail loudly on a stray token: a trailing flag with a missing value, a
+                    // mistyped flag name, or an unexpected positional would otherwise be silently
+                    // ignored while the command still reported success.
+                    writer.WriteLine($"Error: unknown argument '{args[i]}'.");
                     return 1;
-                }
-
-                contextWindow = cw;
             }
         }
 
+        if (contextWindow.HasValue && clearContextWindow)
+        {
+            writer.WriteLine("Error: --context-window and --clear-context-window cannot be combined.");
+            return 1;
+        }
+
+        // An explicit --context-window sets the clamp; --clear-context-window removes it so
+        // detection resolves it; neither leaves the stored value / discovery to decide.
+        var contextWindowOverride = contextWindow is { } cwv
+            ? ValueOverride<int>.Set(cwv)
+            : clearContextWindow ? ValueOverride<int>.Clear : ValueOverride<int>.Unset;
+
+        // An explicit --input/--output-modalities set wins over --clear-modalities (regardless of
+        // arg order); --clear-modalities applies to whichever side was not explicitly set.
+        var inputOverride = inputModalitySet is { } iv
+            ? ValueOverride<ModelModality>.Set(iv)
+            : clearModalities ? ValueOverride<ModelModality>.Clear : ValueOverride<ModelModality>.Unset;
+        var outputOverride = outputModalitySet is { } ov
+            ? ValueOverride<ModelModality>.Set(ov)
+            : clearModalities ? ValueOverride<ModelModality>.Clear : ValueOverride<ModelModality>.Unset;
+
         // Validate role
         var roleKey = role switch
         {
@@ -128,7 +215,9 @@ private static async Task<int> RunSetAsync(
             return 1;
         }
 
-        // Check for context window downgrade
+        // Check for context window downgrade. LoadModelSelection degrades a corrupt current config
+        // to null (this re-set is about to overwrite/repair it), so a bad existing entry skips the
+        // advisory warning instead of aborting the repair.
         var currentModels = LoadModelSelection(paths);
         if (roleKey == "Main" && currentModels?.Main.ContextWindow is > 0 && contextWindow.HasValue)
         {
@@ -139,9 +228,17 @@ private static async Task<int> RunSetAsync(
             }
         }
 
+        // Only an explicit --context-window short-circuits the probe: it supplies the one datum the
+        // probe would discover, so it is the documented "configure this model manually" escape
+        // hatch. A modality override must NOT skip the probe — the probe also validates the model
+        // exists and discovers the context window, and WriteRole already lets an explicit modality
+        // override win over any discovered value, so it is safe to keep probing. --clear-context-window
+        // likewise keeps the probe: "re-detect" is exactly what the probe does.
+        var manualMetadataSupplied = contextWindow.HasValue;
+
         DiscoveredModel? discoveredModel = null;
         var provenance = ModelDiscoverySource.Manual;
-        if (contextWindow is null && ShouldProbeForMetadata(providerEntry))
+        if (!manualMetadataSupplied && ShouldProbeForMetadata(providerEntry))
         {
             probe ??= ProviderCommand.CreateDefaultRegistry();
             ProviderProbeResult probeResult;
@@ -170,15 +267,19 @@ private static async Task<int> RunSetAsync(
         var (config, _) = ConfigFileHelper.LoadConfigFiles(paths);
         var modelsSection = ConfigFileHelper.GetOrCreateSection(config, "Models");
 
-        var modelEntry = ModelEntryWriter.BuildModelEntry(
+        // Definitions own model metadata, so role switches never destroy another model's
+        // operator-owned overrides. Discovery seeds only a new definition; explicit input edits
+        // an existing definition and absence remains runtime detection (#1127, #1610).
+        ModelEntryWriter.WriteRole(
+            modelsSection,
+            roleKey,
             providerName,
             modelId,
             provenance,
-            contextWindow ?? discoveredModel?.ContextWindowTokens,
-            discoveredModel?.InputModalities,
-            discoveredModel?.OutputModalities);
-
-        modelsSection[roleKey] = modelEntry;
+            contextWindowOverride,
+            inputOverride,
+            outputOverride,
+            discoveredModel);
         ConfigFileHelper.WriteConfigFile(paths.NetclawConfigPath, config);
 
         writer.WriteLine($"Set {role} model to {providerName}/{modelId}");
@@ -189,6 +290,59 @@ private static bool ShouldProbeForMetadata(ProviderEntry entry)
         => string.Equals(entry.Type, "openai", StringComparison.OrdinalIgnoreCase)
            && entry.AuthMethod is AuthMethod.OAuthDevice or AuthMethod.OAuthPkce;
 
+    /// <summary>
+    /// Parses a <c>--input/output-modalities</c> value: a comma-separated list of
+    /// <see cref="ModelModality"/> flags (e.g. <c>Text</c>, <c>"Text, Image"</c>). Rejects
+    /// <c>None</c> and any unknown flag so only schema-valid overrides reach config — a model
+    /// with no modalities is meaningless, and <c>--clear-modalities</c> is the way to remove one.
+    /// </summary>
+    private static bool TryParseModalities(string value, out ModelModality modalities, out string error)
+    {
+        const ModelModality all = ModelModality.Text | ModelModality.Image | ModelModality.Audio | ModelModality.Video;
+        modalities = default;
+        error = $"Error: invalid modalities '{value}'. Use a comma-separated list of: Text, Image, Audio, Video "
+                + "(or --clear-modalities to remove the override).";
+
+        var result = ModelModality.None;
+        foreach (var token in value.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            // Enum.TryParse also accepts the underlying integer ("3" → Text|Image), but the contract
+            // advertised in the help text and error message is named flags only. Enum.IsDefined
+            // rejects a numeric token because its parsed value is not a single declared member, so a
+            // mistyped or scripted number is not silently coerced into a modality set.
+            if (!Enum.TryParse(token, ignoreCase: true, out ModelModality parsed)
+                || !Enum.IsDefined(parsed)
+                || parsed == ModelModality.None)
+                return false;
+
+            result |= parsed;
+        }
+
+        if (result == ModelModality.None || (result & ~all) != 0)
+            return false;
+
+        modalities = result;
+        error = string.Empty;
+        return true;
+    }
+
+    /// <summary>
+    /// Consumes the value token following a value-requiring flag, advancing <paramref name="i"/>.
+    /// Returns false when the flag is the final token (its value is missing) so the caller can
+    /// reject it rather than silently dropping the flag.
+    /// </summary>
+    private static bool TryTakeValue(string[] args, ref int i, out string value)
+    {
+        if (i + 1 < args.Length)
+        {
+            value = args[++i];
+            return true;
+        }
+
+        value = string.Empty;
+        return false;
+    }
+
     /// <summary>
     /// The endpoint the probe will actually hit, for display. When a provider has no
     /// explicit endpoint we surface the descriptor's default (e.g. a self-hosted
@@ -305,13 +459,29 @@ private static int RunClear(string[] args, NetclawPaths paths, TextWriter writer
         var (config, _) = ConfigFileHelper.LoadConfigFiles(paths);
         var modelsSection = ConfigFileHelper.GetSectionOrNull(config, "Models");
 
-        if (modelsSection is null || !modelsSection.ContainsKey(roleKey))
+        if (modelsSection is null)
+        {
+            writer.WriteLine($"Role '{role}' is not configured.");
+            return 0;
+        }
+
+        bool removed;
+        try
+        {
+            removed = ModelEntryWriter.ClearRole(modelsSection, roleKey);
+        }
+        catch (Exception ex) when (ex is JsonException or InvalidOperationException)
+        {
+            writer.WriteLine($"Error: {ex.Message}");
+            return 1;
+        }
+
+        if (!removed)
         {
             writer.WriteLine($"Role '{role}' is not configured.");
             return 0;
         }
 
-        modelsSection.Remove(roleKey);
         ConfigFileHelper.WriteConfigFile(paths.NetclawConfigPath, config);
 
         writer.WriteLine($"Cleared {role} model role.");
@@ -319,18 +489,44 @@ private static int RunClear(string[] args, NetclawPaths paths, TextWriter writer
     }
 
     /// <summary>
-    /// Load model selection from config file.
+    /// Loads the model selection, or null when no config / Models section exists OR the config is
+    /// present but unparseable (e.g. a legacy or hand-edited entry with an unrecognized modality
+    /// enum string, which the strict enum-aware deserializer rejects by throwing). The <c>model</c>
+    /// commands are the repair surface for exactly such configs, so they must degrade rather than
+    /// abort with an unhandled JsonException. Callers that must distinguish "absent" from "corrupt"
+    /// — to fail loudly instead of showing a corrupt config as empty — use
+    /// <see cref="TryLoadModelSelection"/>.
     /// </summary>
     internal static ModelSelection? LoadModelSelection(NetclawPaths paths)
+        => TryLoadModelSelection(paths, out var models) ? models : null;
+
+    /// <summary>
+    /// Attempts to load the model selection. Returns false when the config file is present but its
+    /// Models section cannot be parsed, so the caller can report the corruption rather than silently
+    /// treating it as "no models". Returns true (with null <paramref name="models"/>) when no config
+    /// file or Models section exists.
+    /// </summary>
+    internal static bool TryLoadModelSelection(NetclawPaths paths, out ModelSelection? models)
     {
+        models = null;
         if (!File.Exists(paths.NetclawConfigPath))
-            return null;
+            return true;
 
-        using var doc = JsonDocument.Parse(File.ReadAllText(paths.NetclawConfigPath));
-        if (!doc.RootElement.TryGetProperty("Models", out var modelsElement))
-            return null;
-
-        return JsonSerializer.Deserialize<ModelSelection>(modelsElement.GetRawText(), JsonDefaults.EnumAware);
+        try
+        {
+            var configuration = new ConfigurationBuilder()
+                .AddJsonFile(paths.NetclawConfigPath, optional: false, reloadOnChange: false)
+                .Build();
+            if (!configuration.GetSection("Models").Exists())
+                return true;
+
+            models = ModelConfigurationResolver.Resolve(configuration).Selection;
+            return true;
+        }
+        catch (Exception ex) when (ex is JsonException or InvalidOperationException)
+        {
+            return false;
+        }
     }
 
     private static int WriteHelp(TextWriter writer)
@@ -349,11 +545,21 @@ private static int WriteHelp(TextWriter writer)
         writer.WriteLine();
         writer.WriteLine("Options for 'set':");
         writer.WriteLine("  --context-window <tokens>    Override context window size");
+        writer.WriteLine("  --clear-context-window       Remove the context-window override (re-detect from provider)");
+        writer.WriteLine("  --input-modalities <list>    Override input modalities, e.g. \"Text, Image\"");
+        writer.WriteLine("  --output-modalities <list>   Override output modalities, e.g. \"Text\"");
+        writer.WriteLine("  --clear-modalities           Remove modality overrides (fall back to runtime detection)");
+        writer.WriteLine();
+        writer.WriteLine("  Overrides live on named model definitions and survive role switches;");
+        writer.WriteLine("  discovery never rewrites a definition. Use the set or matching clear flag to change it.");
         writer.WriteLine();
         writer.WriteLine("Examples:");
         writer.WriteLine("  netclaw model list");
         writer.WriteLine("  netclaw model discover my-ollama");
         writer.WriteLine("  netclaw model set main my-ollama qwen3:30b --context-window 32768");
+        writer.WriteLine("  netclaw model set main my-openai gpt-x --clear-context-window");
+        writer.WriteLine("  netclaw model set main my-vllm qwen-vl --input-modalities \"Text, Image\"");
+        writer.WriteLine("  netclaw model set main my-ollama qwen3:30b --clear-modalities");
         writer.WriteLine("  netclaw model clear fallback");
         return 0;
     }
diff --git a/src/Netclaw.Cli/Program.cs b/src/Netclaw.Cli/Program.cs
index a00234bf9..f5b953b37 100644
--- a/src/Netclaw.Cli/Program.cs
+++ b/src/Netclaw.Cli/Program.cs
@@ -2001,8 +2001,7 @@ static void ConfigureCliChatServices(IServiceCollection services, IConfiguration
 static ModelCapabilities BuildModelCapabilities(IConfiguration configuration, DaemonApi daemonApi)
 {
     var providers = ProviderConfigurationLoader.Load(configuration.GetSection("Providers"));
-    var models = configuration.GetSection("Models")
-        .Get<ModelSelection>() ?? new ModelSelection();
+    var models = ModelConfigurationResolver.Resolve(configuration).Selection;
     var validation = ProviderRuntimeValidation.Evaluate(
         providers,
         models,
diff --git a/src/Netclaw.Cli/Provider/ProviderRenamer.cs b/src/Netclaw.Cli/Provider/ProviderRenamer.cs
index 07741eb22..ed0620763 100644
--- a/src/Netclaw.Cli/Provider/ProviderRenamer.cs
+++ b/src/Netclaw.Cli/Provider/ProviderRenamer.cs
@@ -96,6 +96,27 @@ private static List<string> CascadeRenameModelRoles(
         var models = ConfigFileHelper.GetSectionOrNull(config, "Models");
         if (models is null) return reassigned;
 
+        if (models.ContainsKey("Definitions"))
+        {
+            var definitions = ConfigFileHelper.GetSectionOrNull(models, "Definitions")
+                              ?? throw new InvalidOperationException("Models:Definitions must be an object.");
+            foreach (var definitionName in definitions.Keys.ToList())
+            {
+                var definition = ConfigFileHelper.GetSectionOrNull(definitions, definitionName);
+                if (definition is null || !definition.TryGetValue("Provider", out var providerValue))
+                    continue;
+                var current = providerValue is JsonElement element
+                    ? element.GetString()
+                    : providerValue as string;
+                if (!string.Equals(current, oldName, StringComparison.OrdinalIgnoreCase))
+                    continue;
+                definition["Provider"] = newName;
+                reassigned.Add(definitionName);
+            }
+
+            return reassigned;
+        }
+
         foreach (var roleName in ModelRoleNames)
         {
             var role = ConfigFileHelper.GetSectionOrNull(models, roleName);
diff --git a/src/Netclaw.Cli/Tui/ModelManagerViewModel.cs b/src/Netclaw.Cli/Tui/ModelManagerViewModel.cs
index 49a9a7f09..4a5410b8e 100644
--- a/src/Netclaw.Cli/Tui/ModelManagerViewModel.cs
+++ b/src/Netclaw.Cli/Tui/ModelManagerViewModel.cs
@@ -95,7 +95,15 @@ public override void OnActivated()
 
     public void Refresh()
     {
-        Models = Model.ModelCommand.LoadModelSelection(_paths);
+        if (!Model.ModelCommand.TryLoadModelSelection(_paths, out var models))
+        {
+            Models = null;
+            StatusMessage.Value = "Model configuration is invalid. Run `netclaw doctor` for details.";
+        }
+        else
+        {
+            Models = models;
+        }
         Providers.Clear();
         var loaded = Provider.ProviderCommand.LoadProviders(_paths);
         foreach (var (name, entry) in loaded.OrderBy(p => p.Key, StringComparer.OrdinalIgnoreCase))
@@ -186,13 +194,20 @@ public void ConfirmAssignment()
         var (config, _) = ConfigFileHelper.LoadConfigFiles(_paths);
         var modelsSection = ConfigFileHelper.GetOrCreateSection(config, "Models");
 
-        modelsSection[roleKey] = ModelEntryWriter.BuildModelEntry(
+        // Non-destructive: re-assigning the same model preserves an existing context-window
+        // clamp and modality overrides, none of which the picker can supply (#1127, #1610). The
+        // picker has no manual-override inputs, so it passes no explicit context window and Unset
+        // modality intent — the probe result seeds a first-time set only; existing values win.
+        ModelEntryWriter.WriteRole(
+            modelsSection,
+            roleKey,
             SelectedProvider,
             SelectedModelId,
             provenance,
-            discoveredModel?.ContextWindowTokens,
-            discoveredModel?.InputModalities,
-            discoveredModel?.OutputModalities);
+            ValueOverride<int>.Unset,
+            ValueOverride<ModelModality>.Unset,
+            ValueOverride<ModelModality>.Unset,
+            discoveredModel);
         ConfigFileHelper.WriteConfigFile(_paths.NetclawConfigPath, config);
 
         Refresh();
@@ -223,7 +238,7 @@ public void ClearRole(string role)
 
         var (config, _) = ConfigFileHelper.LoadConfigFiles(_paths);
         var modelsSection = ConfigFileHelper.GetSectionOrNull(config, "Models");
-        if (modelsSection?.Remove(roleKey) == true)
+        if (modelsSection is not null && ModelEntryWriter.ClearRole(modelsSection, roleKey))
         {
             ConfigFileHelper.WriteConfigFile(_paths.NetclawConfigPath, config);
             Refresh();
diff --git a/src/Netclaw.Cli/Tui/Wizard/Steps/ProviderStepViewModel.cs b/src/Netclaw.Cli/Tui/Wizard/Steps/ProviderStepViewModel.cs
index b40444d2a..4a684e89f 100644
--- a/src/Netclaw.Cli/Tui/Wizard/Steps/ProviderStepViewModel.cs
+++ b/src/Netclaw.Cli/Tui/Wizard/Steps/ProviderStepViewModel.cs
@@ -559,15 +559,9 @@ public SectionContribution BuildContribution(IWizardStepViewModel editor)
         var providerType = vm.SelectedProviderType.ToLowerInvariant();
         var fieldActions = new List<SectionFieldAction>
         {
-            new("Providers", SectionFieldActionKind.Set, BuildProvidersDictionary(vm, providerType)),
-            new("Models.Main.Provider", SectionFieldActionKind.Set, providerType)
+            new("Providers", SectionFieldActionKind.Set, BuildProvidersDictionary(vm, providerType))
         };
 
-        if (string.IsNullOrWhiteSpace(vm.SelectedModelId))
-            fieldActions.Add(new SectionFieldAction("Models.Main.ModelId", SectionFieldActionKind.Delete));
-        else
-            fieldActions.Add(new SectionFieldAction("Models.Main.ModelId", SectionFieldActionKind.Set, vm.SelectedModelId));
-
         var secretPath = $"Providers.{providerType}";
         var secretActions = new List<SectionSecretAction>();
         if (!string.IsNullOrWhiteSpace(vm.ApiKeyInput))
diff --git a/src/Netclaw.Cli/Tui/Wizard/WizardConfigBuilder.cs b/src/Netclaw.Cli/Tui/Wizard/WizardConfigBuilder.cs
index f8bc4bf18..bac870f88 100644
--- a/src/Netclaw.Cli/Tui/Wizard/WizardConfigBuilder.cs
+++ b/src/Netclaw.Cli/Tui/Wizard/WizardConfigBuilder.cs
@@ -135,13 +135,22 @@ internal Dictionary<string, object> BuildConfigDictionary()
         if (Model is not null)
         {
             var models = ConfigFileHelper.GetOrCreateSection(config, "Models");
-            models["Main"] = ModelEntryWriter.BuildModelEntry(
+            ModelEntryWriter.WriteRole(
+                models,
+                "Main",
                 Model.Provider,
                 Model.ModelId,
                 Model.Provenance,
-                Model.ContextWindow,
-                Model.InputModalities,
-                Model.OutputModalities);
+                Model.ContextWindow is { } contextWindow
+                    ? ValueOverride<int>.Set(contextWindow)
+                    : ValueOverride<int>.Unset,
+                Model.InputModalities is { } input
+                    ? ValueOverride<ModelModality>.Set(input)
+                    : ValueOverride<ModelModality>.Unset,
+                Model.OutputModalities is { } output
+                    ? ValueOverride<ModelModality>.Set(output)
+                    : ValueOverride<ModelModality>.Unset,
+                discovered: null);
         }
 
         // Slack section
diff --git a/src/Netclaw.Configuration.Tests/NamedModelConfigurationTests.cs b/src/Netclaw.Configuration.Tests/NamedModelConfigurationTests.cs
new file mode 100644
index 000000000..42dbefa0e
--- /dev/null
+++ b/src/Netclaw.Configuration.Tests/NamedModelConfigurationTests.cs
@@ -0,0 +1,86 @@
+// -----------------------------------------------------------------------
+// <copyright file="NamedModelConfigurationTests.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+using Microsoft.Extensions.Configuration;
+using Xunit;
+
+namespace Netclaw.Configuration.Tests;
+
+public sealed class NamedModelConfigurationTests
+{
+    [Fact]
+    public void Resolve_LegacyShape_PreservesRuntimeValues()
+    {
+        var configuration = Build(new Dictionary<string, string?>
+        {
+            ["Models:Main:Provider"] = "vllm",
+            ["Models:Main:ModelId"] = "qwen-vl",
+            ["Models:Main:ContextWindow"] = "32768",
+            ["Models:Main:InputModalities"] = "Text, Image",
+        });
+
+        var result = ModelConfigurationResolver.Resolve(configuration);
+
+        Assert.True(result.IsLegacy);
+        Assert.Equal("vllm", result.Selection.Main.Provider);
+        Assert.Equal(32768, result.Selection.Main.ContextWindow);
+        Assert.Equal(ModelModality.Text | ModelModality.Image, result.Selection.Main.InputModalities);
+    }
+
+    [Fact]
+    public void Resolve_NamedShape_ResolvesRoleWithoutMutatingDefinition()
+    {
+        var configuration = Build(new Dictionary<string, string?>
+        {
+            ["Models:Definitions:vision:Provider"] = "vllm",
+            ["Models:Definitions:vision:ModelId"] = "qwen-vl",
+            ["Models:Definitions:vision:InputModalities"] = "Text, Image",
+            ["Models:Roles:Main"] = "vision",
+        });
+
+        var result = ModelConfigurationResolver.Resolve(configuration);
+
+        Assert.False(result.IsLegacy);
+        Assert.Equal("qwen-vl", result.Selection.Main.ModelId);
+        Assert.Equal(ModelModality.Text | ModelModality.Image, result.Selection.Main.InputModalities);
+    }
+
+    [Fact]
+    public void Resolve_MixedShape_FailsLoudly()
+    {
+        var configuration = Build(new Dictionary<string, string?>
+        {
+            ["Models:Main:Provider"] = "vllm",
+            ["Models:Main:ModelId"] = "qwen-vl",
+            ["Models:Definitions:vision:Provider"] = "vllm",
+            ["Models:Definitions:vision:ModelId"] = "qwen-vl",
+            ["Models:Roles:Main"] = "vision",
+        });
+
+        var exception = Assert.Throws<InvalidOperationException>(
+            () => ModelConfigurationResolver.Resolve(configuration));
+
+        Assert.Contains("mixes legacy", exception.Message);
+    }
+
+    [Fact]
+    public void Resolve_MissingDefinition_FailsLoudly()
+    {
+        var configuration = Build(new Dictionary<string, string?>
+        {
+            ["Models:Definitions:vision:Provider"] = "vllm",
+            ["Models:Definitions:vision:ModelId"] = "qwen-vl",
+            ["Models:Roles:Main"] = "missing",
+        });
+
+        var exception = Assert.Throws<InvalidOperationException>(
+            () => ModelConfigurationResolver.Resolve(configuration));
+
+        Assert.Contains("unknown definition 'missing'", exception.Message);
+    }
+
+    private static IConfiguration Build(Dictionary<string, string?> values)
+        => new ConfigurationBuilder().AddInMemoryCollection(values).Build();
+}
diff --git a/src/Netclaw.Configuration.Tests/ProviderRuntimeValidationTests.cs b/src/Netclaw.Configuration.Tests/ProviderRuntimeValidationTests.cs
index 3d84e1801..b3f9e2c43 100644
--- a/src/Netclaw.Configuration.Tests/ProviderRuntimeValidationTests.cs
+++ b/src/Netclaw.Configuration.Tests/ProviderRuntimeValidationTests.cs
@@ -3,12 +3,46 @@
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
 // -----------------------------------------------------------------------
+using System.Text.Json.Nodes;
 using Xunit;
 
 namespace Netclaw.Configuration.Tests;
 
 public sealed class ProviderRuntimeValidationTests
 {
+    [Theory]
+    [InlineData("vision", true, true, true)]
+    [InlineData("VISION", true, true, true)]
+    [InlineData("missing", true, false, false)]
+    [InlineData("provider-only", true, true, false)]
+    [InlineData(null, false, false, false)]
+    public void NamedRolePresence_ComesFromReferencedDefinition(
+        string? roleReference,
+        bool roleConfigured,
+        bool providerConfigured,
+        bool modelIdConfigured)
+    {
+        var models = JsonNode.Parse(
+            """
+            {
+              "Definitions": {
+                "vision": { "Provider": "vllm", "ModelId": "qwen-vl" },
+                "provider-only": { "Provider": "vllm" }
+              },
+              "Roles": {}
+            }
+            """)!.AsObject();
+        if (roleReference is not null)
+            models["Roles"]!["Main"] = roleReference;
+
+        var root = new JsonObject { ["Models"] = models };
+        var result = ProviderRuntimeConfiguration.FromJson(root).Main;
+
+        Assert.Equal(roleConfigured, result.RoleConfigured);
+        Assert.Equal(providerConfigured, result.ProviderConfigured);
+        Assert.Equal(modelIdConfigured, result.ModelIdConfigured);
+    }
+
     [Fact]
     public void MainModelAbsent_DefaultModelSelection_ReturnsNoProviderConfigured()
     {
diff --git a/src/Netclaw.Configuration/NamedModelConfiguration.cs b/src/Netclaw.Configuration/NamedModelConfiguration.cs
new file mode 100644
index 000000000..5d45997ea
--- /dev/null
+++ b/src/Netclaw.Configuration/NamedModelConfiguration.cs
@@ -0,0 +1,126 @@
+// -----------------------------------------------------------------------
+// <copyright file="NamedModelConfiguration.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+using Microsoft.Extensions.Configuration;
+
+namespace Netclaw.Configuration;
+
+/// <summary>
+/// Canonical model configuration. Definitions own model metadata; roles only select definitions.
+/// </summary>
+public sealed class NamedModelConfiguration
+{
+    public Dictionary<string, ModelReference> Definitions { get; set; } =
+        new(StringComparer.OrdinalIgnoreCase);
+
+    public ModelRoleAssignments Roles { get; set; } = new();
+}
+
+public sealed class ModelRoleAssignments
+{
+    public string Main { get; set; } = string.Empty;
+    public string? Fallback { get; set; }
+    public string? Compaction { get; set; }
+}
+
+/// <summary>
+/// Resolves either the legacy inline role shape or the canonical named-definition shape into the
+/// runtime representation consumed by provider and actor composition. Mixed shapes fail loudly.
+/// </summary>
+public static class ModelConfigurationResolver
+{
+    private static readonly string[] LegacyRoles = ["Main", "Fallback", "Compaction"];
+
+    public static ModelConfigurationResolution Resolve(IConfigurationSection modelsSection)
+    {
+        var hasLegacy = LegacyRoles.Any(role => modelsSection.GetSection(role).Exists());
+        var hasDefinitions = modelsSection.GetSection(nameof(NamedModelConfiguration.Definitions)).Exists();
+        var hasRoles = modelsSection.GetSection(nameof(NamedModelConfiguration.Roles)).Exists();
+        var hasNamed = hasDefinitions || hasRoles;
+
+        if (hasLegacy && hasNamed)
+            throw new InvalidOperationException(
+                "Models configuration mixes legacy inline roles with named Definitions/Roles. " +
+                "Run `netclaw doctor --fix` after removing one representation.");
+
+        if (!hasNamed)
+        {
+            return new ModelConfigurationResolution(
+                modelsSection.Get<ModelSelection>() ?? new ModelSelection(),
+                IsLegacy: hasLegacy);
+        }
+
+        if (!hasDefinitions || !hasRoles)
+            throw new InvalidOperationException(
+                "Named Models configuration requires both Definitions and Roles sections.");
+
+        var duplicateDefinition = modelsSection.GetSection(nameof(NamedModelConfiguration.Definitions))
+            .GetChildren()
+            .GroupBy(child => child.Key, StringComparer.OrdinalIgnoreCase)
+            .FirstOrDefault(group => group.Count() > 1);
+        if (duplicateDefinition is not null)
+        {
+            throw new InvalidOperationException(
+                $"Models:Definitions contains duplicate case-insensitive name '{duplicateDefinition.Key}'.");
+        }
+
+        var named = modelsSection.Get<NamedModelConfiguration>() ?? new NamedModelConfiguration();
+        if (named.Definitions.Count == 0)
+            throw new InvalidOperationException("Models:Definitions must contain at least one model definition.");
+
+        var selection = new ModelSelection
+        {
+            Main = ResolveRequired(named, nameof(named.Roles.Main), named.Roles.Main),
+            Fallback = ResolveOptional(named, nameof(named.Roles.Fallback), named.Roles.Fallback),
+            Compaction = ResolveOptional(named, nameof(named.Roles.Compaction), named.Roles.Compaction),
+        };
+
+        return new ModelConfigurationResolution(selection, IsLegacy: false);
+    }
+
+    public static ModelConfigurationResolution Resolve(IConfiguration configuration)
+        => Resolve(configuration.GetSection("Models"));
+
+    private static ModelReference ResolveRequired(
+        NamedModelConfiguration named, string role, string definitionName)
+    {
+        if (string.IsNullOrWhiteSpace(definitionName))
+            throw new InvalidOperationException($"Models:Roles:{role} must reference a model definition.");
+
+        return ResolveDefinition(named, role, definitionName);
+    }
+
+    private static ModelReference? ResolveOptional(
+        NamedModelConfiguration named, string role, string? definitionName)
+        => string.IsNullOrWhiteSpace(definitionName)
+            ? null
+            : ResolveDefinition(named, role, definitionName);
+
+    private static ModelReference ResolveDefinition(
+        NamedModelConfiguration named, string role, string definitionName)
+    {
+        var match = named.Definitions.FirstOrDefault(pair =>
+            string.Equals(pair.Key, definitionName, StringComparison.OrdinalIgnoreCase));
+        if (string.IsNullOrEmpty(match.Key))
+        {
+            throw new InvalidOperationException(
+                $"Models:Roles:{role} references unknown definition '{definitionName}'.");
+        }
+
+        return Clone(match.Value);
+    }
+
+    private static ModelReference Clone(ModelReference source) => new()
+    {
+        Provider = source.Provider,
+        ModelId = source.ModelId,
+        ContextWindow = source.ContextWindow,
+        Provenance = source.Provenance,
+        InputModalities = source.InputModalities,
+        OutputModalities = source.OutputModalities,
+    };
+}
+
+public sealed record ModelConfigurationResolution(ModelSelection Selection, bool IsLegacy);
diff --git a/src/Netclaw.Configuration/ProviderRuntimeValidation.cs b/src/Netclaw.Configuration/ProviderRuntimeValidation.cs
index be21c1027..9c9c94ca6 100644
--- a/src/Netclaw.Configuration/ProviderRuntimeValidation.cs
+++ b/src/Netclaw.Configuration/ProviderRuntimeValidation.cs
@@ -182,6 +182,18 @@ public static ProviderRuntimeConfiguration FromConfiguration(IConfiguration conf
         var models = configuration.GetSection("Models");
         var providers = configuration.GetSection("Providers");
 
+        if (models.GetSection(nameof(NamedModelConfiguration.Definitions)).Exists()
+            || models.GetSection(nameof(NamedModelConfiguration.Roles)).Exists())
+        {
+            var selection = ModelConfigurationResolver.Resolve(models).Selection;
+            return FromExplicitRoles(
+                ProviderConfigurationLoader.Load(providers),
+                main: !string.IsNullOrWhiteSpace(selection.Main.Provider)
+                      && !string.IsNullOrWhiteSpace(selection.Main.ModelId),
+                fallback: selection.Fallback is not null,
+                compaction: selection.Compaction is not null);
+        }
+
         return new ProviderRuntimeConfiguration(
             Main: ModelReferenceRuntimeConfiguration.FromConfiguration(models.GetSection("Main")),
             Fallback: ModelReferenceRuntimeConfiguration.FromConfiguration(models.GetSection("Fallback")),
@@ -197,6 +209,21 @@ public static ProviderRuntimeConfiguration FromJson(JsonObject? root)
         var models = root?["Models"] as JsonObject;
         var providers = root?["Providers"] as JsonObject;
 
+        if (models?["Roles"] is JsonObject roles)
+        {
+            var definitions = models["Definitions"] as JsonObject;
+            return new ProviderRuntimeConfiguration(
+                Main: ModelReferenceRuntimeConfiguration.FromNamedRole(roles, definitions, "Main"),
+                Fallback: ModelReferenceRuntimeConfiguration.FromNamedRole(roles, definitions, "Fallback"),
+                Compaction: ModelReferenceRuntimeConfiguration.FromNamedRole(roles, definitions, "Compaction"),
+                ProvidersWithExplicitType: providers is null
+                    ? []
+                    : providers
+                        .Where(provider => provider.Value is JsonObject obj && HasProperty(obj, nameof(ProviderEntry.Type)))
+                        .Select(provider => provider.Key)
+                        .ToList());
+        }
+
         return new ProviderRuntimeConfiguration(
             Main: ModelReferenceRuntimeConfiguration.FromJson(models?["Main"] as JsonObject),
             Fallback: ModelReferenceRuntimeConfiguration.FromJson(models?["Fallback"] as JsonObject),
@@ -227,6 +254,7 @@ public static ProviderRuntimeConfiguration FromExplicitRoles(
 
     internal static bool HasProperty(JsonObject obj, string propertyName) =>
         obj.Any(property => string.Equals(property.Key, propertyName, StringComparison.OrdinalIgnoreCase));
+
 }
 
 public sealed record ModelReferenceRuntimeConfiguration(
@@ -250,6 +278,33 @@ public static ModelReferenceRuntimeConfiguration FromJson(JsonObject? obj)
             ModelIdConfigured: obj is not null && ProviderRuntimeConfiguration.HasProperty(obj, nameof(ModelReference.ModelId)));
     }
 
+    public static ModelReferenceRuntimeConfiguration FromNamedRole(
+        JsonObject roles, JsonObject? definitions, string roleName)
+    {
+        var role = roles.FirstOrDefault(property =>
+            string.Equals(property.Key, roleName, StringComparison.OrdinalIgnoreCase));
+        if (role.Value is not JsonValue roleValue
+            || !roleValue.TryGetValue<string>(out var definitionName)
+            || string.IsNullOrWhiteSpace(definitionName))
+        {
+            return FromCompleteRole(false);
+        }
+
+        var definition = definitions?
+            .FirstOrDefault(property => string.Equals(
+                property.Key, definitionName, StringComparison.OrdinalIgnoreCase))
+            .Value as JsonObject;
+
+        return new ModelReferenceRuntimeConfiguration(
+            RoleConfigured: true,
+            ProviderConfigured: definition is not null
+                                && ProviderRuntimeConfiguration.HasProperty(
+                                    definition, nameof(ModelReference.Provider)),
+            ModelIdConfigured: definition is not null
+                               && ProviderRuntimeConfiguration.HasProperty(
+                                   definition, nameof(ModelReference.ModelId)));
+    }
+
     public static ModelReferenceRuntimeConfiguration FromCompleteRole(bool configured) =>
         configured
             ? new ModelReferenceRuntimeConfiguration(true, true, true)
diff --git a/src/Netclaw.Configuration/Schemas/netclaw-config.v1.schema.json b/src/Netclaw.Configuration/Schemas/netclaw-config.v1.schema.json
index a183c0bb2..83c0064dd 100644
--- a/src/Netclaw.Configuration/Schemas/netclaw-config.v1.schema.json
+++ b/src/Netclaw.Configuration/Schemas/netclaw-config.v1.schema.json
@@ -333,14 +333,40 @@
       "additionalProperties": true
     },
     "Models": {
-      "type": "object",
-      "description": "Model selection by role (Main, Fallback, Compaction).",
-      "properties": {
-        "Main": { "$ref": "#/$defs/ModelReference" },
-        "Fallback": { "$ref": "#/$defs/ModelReference" },
-        "Compaction": { "$ref": "#/$defs/ModelReference" }
-      },
-      "additionalProperties": false
+      "description": "Named model definitions and role assignments. The legacy inline role shape remains accepted for upgrades.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "Main": { "$ref": "#/$defs/ModelReference" },
+            "Fallback": { "$ref": "#/$defs/ModelReference" },
+            "Compaction": { "$ref": "#/$defs/ModelReference" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["Definitions", "Roles"],
+          "properties": {
+            "Definitions": {
+              "type": "object",
+              "minProperties": 1,
+              "additionalProperties": { "$ref": "#/$defs/ModelReference" }
+            },
+            "Roles": {
+              "type": "object",
+              "required": ["Main"],
+              "properties": {
+                "Main": { "type": "string", "minLength": 1 },
+                "Fallback": { "type": ["string", "null"] },
+                "Compaction": { "type": ["string", "null"] }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
     },
     "Memory": {
       "type": "object",
diff --git a/src/Netclaw.Daemon/Program.cs b/src/Netclaw.Daemon/Program.cs
index d40dc308c..95f16f595 100644
--- a/src/Netclaw.Daemon/Program.cs
+++ b/src/Netclaw.Daemon/Program.cs
@@ -360,8 +360,7 @@ static NetclawPaths ConfigureConfigServices(IServiceCollection services, IConfig
     // No silent fallback to local-ollama: an empty Providers section yields
     // the NoProviderConfigured outcome and the host registers NoOpChatClientProvider.
     var providers = ProviderConfigurationLoader.Load(configuration.GetSection("Providers"));
-    var models = configuration.GetSection("Models")
-        .Get<ModelSelection>() ?? new ModelSelection();
+    var models = ModelConfigurationResolver.Resolve(configuration).Selection;
     var validation = ProviderRuntimeValidation.Evaluate(
         providers,
         models,
@@ -398,9 +397,15 @@ static void ConfigureDaemonServices(
     services.AddHostedService<ExposureModeValidationService>();
     services.AddHostedService<BootstrapCompletionMarkerService>();
 
+    var resolvedModels = ModelConfigurationResolver.Resolve(configuration).Selection;
     services
         .AddOptions<ModelSelection>()
-        .Bind(configuration.GetSection("Models"))
+        .Configure(options =>
+        {
+            options.Main = resolvedModels.Main;
+            options.Fallback = resolvedModels.Fallback;
+            options.Compaction = resolvedModels.Compaction;
+        })
         .ValidateOnStart();
     services.AddSingleton<IValidateOptions<ModelSelection>, ModelSelectionValidator>();
     services
@@ -418,8 +423,7 @@ static void ConfigureDaemonServices(
     });
 
     // Resolve models for session config
-    var models = configuration.GetSection("Models")
-        .Get<ModelSelection>() ?? new ModelSelection();
+    var models = resolvedModels;
     services.AddSingleton(models);
 
     // Auto-detect model capabilities via the runtime IModelCapabilityResolver
diff --git a/tests/smoke/assertions/init-wizard.sh b/tests/smoke/assertions/init-wizard.sh
index cd0df752a..11c513222 100755
--- a/tests/smoke/assertions/init-wizard.sh
+++ b/tests/smoke/assertions/init-wizard.sh
@@ -47,8 +47,9 @@ fi
 echo "init-wizard: checking expected fields in netclaw.json..."
 assert_field '.Providers.ollama.Type'       'ollama'                   "$config_json" || :
 assert_field '.Providers.ollama.Endpoint'   'http://localhost:11434'   "$config_json" || :
-assert_field '.Models.Main.Provider'        'ollama'                   "$config_json" || :
-assert_field '.Models.Main.ModelId'         'qwen2:0.5b'               "$config_json" || :
+assert_field '.Models.Roles.Main'                                  'ollama-qwen2-0-5b' "$config_json" || :
+assert_field '.Models.Definitions[.Models.Roles.Main].Provider'     'ollama'             "$config_json" || :
+assert_field '.Models.Definitions[.Models.Roles.Main].ModelId'      'qwen2:0.5b'         "$config_json" || :
 assert_field '.Security.DeploymentPosture'  'Personal'                 "$config_json" || :
 
 echo "init-wizard: checking identity/SOUL.md for typed user name..."

From f71aceb8f128de3be72504f5396b947143832bde Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 12 Jul 2026 00:59:21 +0000
Subject: [PATCH 7/9] chore(deps): bump dotnet-sdk from 10.0.300 to 10.0.301
 (#1381)

Bumps [dotnet-sdk](https://github.com/dotnet/sdk) from 10.0.300 to 10.0.301.
- [Release notes](https://github.com/dotnet/sdk/releases)
- [Commits](https://github.com/dotnet/sdk/compare/v10.0.300...v10.0.301)

---
updated-dependencies:
- dependency-name: dotnet-sdk
  dependency-version: 10.0.301
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 global.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/global.json b/global.json
index ce3fe091c..206e7553c 100644
--- a/global.json
+++ b/global.json
@@ -1,6 +1,6 @@
 {
     "sdk": {
-        "version": "10.0.300",
+        "version": "10.0.301",
         "rollForward": "major"
     }
 } 
\ No newline at end of file

From 2f0b72df14872f23652ee754b16ef6d122072ed9 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sat, 11 Jul 2026 19:59:43 -0500
Subject: [PATCH 8/9] fix(subagents): fail closed for unattended approvals
 (#1616)

---
 .../SessionToolExecutionPipelineTests.cs      |  68 ++++++++++++
 .../SubAgents/SubAgentSpawnerTests.cs         | 100 ++++++++++++++++++
 .../Pipelines/SessionToolExecutionPipeline.cs |   4 +-
 .../SubAgents/SubAgentSpawner.cs              |   7 +-
 4 files changed, 177 insertions(+), 2 deletions(-)

diff --git a/src/Netclaw.Actors.Tests/Sessions/SessionToolExecutionPipelineTests.cs b/src/Netclaw.Actors.Tests/Sessions/SessionToolExecutionPipelineTests.cs
index 7613ecacf..0a999894a 100644
--- a/src/Netclaw.Actors.Tests/Sessions/SessionToolExecutionPipelineTests.cs
+++ b/src/Netclaw.Actors.Tests/Sessions/SessionToolExecutionPipelineTests.cs
@@ -148,6 +148,54 @@ public async Task Source_less_approval_required_turn_fails_closed_without_prompt
         Assert.Empty(approvals);
     }
 
+    [Theory]
+    [InlineData(ChannelType.Headless)]
+    [InlineData(ChannelType.Reminder)]
+    [InlineData(ChannelType.Webhook)]
+    public async Task Non_interactive_turn_does_not_create_subagent_approval_bridge(ChannelType channelType)
+    {
+        var executor = new ContextCapturingExecutor();
+        var probe = CreateTestProbe($"non-interactive-{channelType}-context-probe");
+        var sessionId = new SessionId($"automation/{channelType}");
+        var source = new MessageSource
+        {
+            ChannelType = channelType,
+            SenderId = new SenderId("automation"),
+            Audience = TrustAudience.Personal,
+            Boundary = TrustBoundary.Personal,
+            Principal = PrincipalClassification.VerifiedAutomation,
+            Provenance = new SourceProvenance(TransportAuthenticity.LocalProcess, PayloadTaint.Trusted),
+            ReceivedAt = DateTimeOffset.UnixEpoch
+        };
+
+        var pipelineTask = SessionToolExecutionPipeline.ExecuteToolsAsync(
+            executor,
+            [new FunctionCallContent("call-1", "inspect_context")],
+            sessionId,
+            source,
+            auditLogger: null,
+            timeProvider: TimeProvider.System,
+            sessionDir: Path.GetTempPath(),
+            maxInlineToolResultChars: 4096,
+            timeout: TimeSpan.FromSeconds(1),
+            self: probe.Ref,
+            emitSubAgentOutput: _ => { },
+            spawnChildActor: static (_, _, _) => Task.FromResult<object>(new object()),
+            approvalChannel: new ApprovalChannel(),
+            emitApprovalRequest: _ => { },
+            approvalTimeout: Timeout.InfiniteTimeSpan,
+            ct: TestContext.Current.CancellationToken);
+
+        await probe.ExpectMsgAsync<ToolExecutionCompleted>(
+            TimeSpan.FromSeconds(3),
+            cancellationToken: TestContext.Current.CancellationToken);
+        await pipelineTask.WaitAsync(TimeSpan.FromSeconds(3), TestContext.Current.CancellationToken);
+
+        Assert.NotNull(executor.Context);
+        Assert.False(executor.Context.SupportsInteractiveApproval);
+        Assert.Null(executor.Context.ApprovalBridge);
+    }
+
     [Fact]
     public async Task Approve_once_does_not_reprompt_on_retry_execution()
     {
@@ -837,6 +885,26 @@ public Task<string> ExecuteAsync(FunctionCallContent toolCall, ToolExecutionCont
         }
     }
 
+    private sealed class ContextCapturingExecutor : IToolExecutor
+    {
+        public ToolExecutionContext? Context { get; private set; }
+
+        public Task AuthorizeAsync(
+            FunctionCallContent toolCall,
+            ToolExecutionContext? context = null,
+            CancellationToken ct = default)
+            => Task.CompletedTask;
+
+        public Task<string> ExecuteAsync(
+            FunctionCallContent toolCall,
+            ToolExecutionContext? context = null,
+            CancellationToken ct = default)
+        {
+            Context = context;
+            return Task.FromResult("ok");
+        }
+    }
+
     private sealed class ApprovalWithCwdExecutor(string cwd) : IToolExecutor
     {
         private int _attempt;
diff --git a/src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnerTests.cs b/src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnerTests.cs
index 64062c599..d04aca85a 100644
--- a/src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnerTests.cs
+++ b/src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnerTests.cs
@@ -8,6 +8,7 @@
 using Akka.Hosting.TestKit;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Logging.Abstractions;
+using Netclaw.Actors.Channels;
 using Netclaw.Actors.SubAgents;
 using Netclaw.Actors.Tests.Memory;
 using Netclaw.Actors.Tools;
@@ -90,6 +91,68 @@ public async Task Spawn_async_propagates_parent_resolved_cwd_on_run_message()
         Assert.True(result.Success);
     }
 
+    [Theory]
+    [InlineData(ChannelType.Headless)]
+    [InlineData(ChannelType.Reminder)]
+    [InlineData(ChannelType.Webhook)]
+    public async Task Spawn_async_does_not_bridge_approval_for_non_interactive_parent(ChannelType channelType)
+    {
+        var childProbe = CreateTestProbe($"non-interactive-{channelType}-child");
+        var spawner = CreateSpawner();
+        var context = new ToolExecutionContext("automation/subagent-parent", "/tmp/netclaw/sessions/parent")
+        {
+            Audience = TrustAudience.Personal,
+            ChannelType = channelType.ToWireValue(),
+            SupportsInteractiveApproval = false,
+            ApprovalBridge = new RecordingParentApprovalBridge(ParentApprovalDecision.ApprovedOnce),
+            SpawnChildActor = (_, _, _) => Task.FromResult<object>(childProbe.Ref)
+        };
+
+        var spawnTask = spawner.SpawnAsync(
+            CreateProfile(),
+            "Inspect the system.",
+            runtimeContext: null,
+            context,
+            TestContext.Current.CancellationToken);
+
+        var run = await childProbe.ExpectMsgAsync<RunSubAgent>(
+            cancellationToken: TestContext.Current.CancellationToken);
+        Assert.Null(run.ApprovalBridge);
+
+        childProbe.Reply(SuccessfulResult());
+        Assert.True((await spawnTask).Success);
+    }
+
+    [Fact]
+    public async Task Spawn_async_preserves_approval_bridge_for_interactive_parent()
+    {
+        var childProbe = CreateTestProbe("interactive-approval-child");
+        var approvalBridge = new RecordingParentApprovalBridge(ParentApprovalDecision.ApprovedOnce);
+        var spawner = CreateSpawner();
+        var context = new ToolExecutionContext("interactive/subagent-parent", "/tmp/netclaw/sessions/parent")
+        {
+            Audience = TrustAudience.Personal,
+            ChannelType = ChannelType.Tui.ToWireValue(),
+            SupportsInteractiveApproval = true,
+            ApprovalBridge = approvalBridge,
+            SpawnChildActor = (_, _, _) => Task.FromResult<object>(childProbe.Ref)
+        };
+
+        var spawnTask = spawner.SpawnAsync(
+            CreateProfile(),
+            "Inspect the system.",
+            runtimeContext: null,
+            context,
+            TestContext.Current.CancellationToken);
+
+        var run = await childProbe.ExpectMsgAsync<RunSubAgent>(
+            cancellationToken: TestContext.Current.CancellationToken);
+        Assert.Same(approvalBridge, run.ApprovalBridge);
+
+        childProbe.Reply(SuccessfulResult());
+        Assert.True((await spawnTask).Success);
+    }
+
     [Fact]
     public async Task Spawn_async_ignores_definition_tool_metadata_for_runtime_tool_resolution()
     {
@@ -213,4 +276,41 @@ public async Task Spawned_sub_agent_bills_its_llm_calls_to_session_metrics()
         var call = Assert.Single(metrics.TokenUsageCalls);
         Assert.Equal((175L, 60L), call);
     }
+
+    private static SubAgentSpawner CreateSpawner()
+    {
+        var toolRegistry = new ToolRegistry();
+        toolRegistry.Register(new FakeNetclawTool("inspect_context", "ok"));
+
+        return new SubAgentSpawner(
+            new SingleClientProvider(new FakeChatClient()),
+            toolRegistry,
+            new ToolAccessPolicy(
+                new ToolConfig(),
+                new EffectivePolicyDefaults(
+                    DeploymentPosture.Personal,
+                    TrustAudience.Personal,
+                    ShellExecutionMode.HostAllowed,
+                    UsedStrictFallback: false),
+                new ShellCommandPolicy()),
+            approvalService: null,
+            new StaticSystemPromptProvider("You are an inspector."),
+            NullLogger<SubAgentSpawner>.Instance);
+    }
+
+    private static SubAgentProfile CreateProfile() => new()
+    {
+        Name = "inspector",
+        Description = "Inspect the system",
+        SystemPrompt = "You are an inspector.",
+        ToolNames = ["inspect_context"],
+        Visibility = SubAgentVisibility.UserFacing
+    };
+
+    private static SubAgentResult SuccessfulResult() => new()
+    {
+        Success = true,
+        Output = "ok",
+        AgentName = new AgentName("inspector")
+    };
 }
diff --git a/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs b/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs
index 45cd08f59..5f35de5f1 100644
--- a/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs
+++ b/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs
@@ -270,7 +270,9 @@ public static async Task<ToolCallResult> ExecuteSingleToolAsync(
             context.OneTimeApprovedToolName = tc.Name;
             context.SetOneTimeApprovedPatterns(oneTimeApprovalPreSeed);
         }
-        if (approvalChannel is not null && emitApprovalRequest is not null)
+        if (approvalChannel is not null
+            && emitApprovalRequest is not null
+            && CanRequestInteractiveApproval(source, turnContext))
         {
             context.ApprovalBridge = new ParentSessionApprovalBridge(
                 approvalChannel,
diff --git a/src/Netclaw.Actors/SubAgents/SubAgentSpawner.cs b/src/Netclaw.Actors/SubAgents/SubAgentSpawner.cs
index 530cda8b1..52fd47cea 100644
--- a/src/Netclaw.Actors/SubAgents/SubAgentSpawner.cs
+++ b/src/Netclaw.Actors/SubAgents/SubAgentSpawner.cs
@@ -201,7 +201,12 @@ public async Task<SubAgentResult> SpawnAsync(
                     ParentProjectDirectory = context.ProjectDirectory,
                     ParentCwd = context.ResolveShellCwd(null),
                     Cancellation = ct,
-                    ApprovalBridge = context.ApprovalBridge,
+                    // A session owns an approval channel even when its transport cannot
+                    // service prompts. Preserve the channel capability as the authority:
+                    // bridge presence alone must never make an unattended child interactive.
+                    ApprovalBridge = context.SupportsInteractiveApproval == true
+                        ? context.ApprovalBridge
+                        : null,
                     // Null for non-streaming callers such as routed skills and the
                     // legacy ExecuteAsync path; the sub-agent surfaces its progress
                     // through its own session-correlated logs regardless. Streaming

From 11b4072ab8ec3c862e5a5ec164c991a486fceeff Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Sun, 12 Jul 2026 16:00:16 +0000
Subject: [PATCH 9/9] chore(release): prepare 0.25.0-alpha.onnx.5 experimental
 prerelease

---
 Directory.Build.props |  2 +-
 RELEASE_NOTES.md      | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/Directory.Build.props b/Directory.Build.props
index 3d967ef63..a9f59e71b 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -9,7 +9,7 @@
     <Nullable>enable</Nullable>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <VersionPrefix>0.25.0</VersionPrefix>
-    <VersionSuffix>alpha.onnx.4</VersionSuffix>
+    <VersionSuffix>alpha.onnx.5</VersionSuffix>
     <PackageReleaseNotes>Netclaw v0.25.0-beta.1 — SkillServer native sub-agent sync, memory curation unification, systemd PATH fix
 
 **Features**
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 442124825..92287b935 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,5 +1,28 @@
 # NetClaw Release Notes
 
+## 0.25.0-alpha.onnx.5 (2026-07-12)
+
+> **Experimental feature build** (fifth in the memory-embeddings series). This build carries
+> **no changes to memory/embeddings behavior** versus `0.25.0-alpha.onnx.4` — it merges the
+> mainline `dev` branch to bring the experimental line current with recent fixes, most
+> importantly a fail-closed hardening of unattended sub-agent approvals. Same gating as before:
+> everything rides `Memory.Embeddings.Enabled`, off by default; install only by exact pin
+> (`NETCLAW_VERSION=0.25.0-alpha.onnx.5`). Upgrading from alpha.onnx.4 is a binary swap — no
+> config, data, or unit changes.
+
+### Security
+- **Fail-closed unattended sub-agent approvals** — a sub-agent spawned from a session whose transport cannot service interactive approval prompts no longer inherits an approval bridge from the parent context; bridge presence alone can never make an unattended child interactive. Prevents an approval-gated tool from becoming silently auto-approvable in headless, webhook, and reminder-driven turns ([#1616](https://github.com/netclaw-dev/netclaw/pull/1616))
+
+### Bug Fixes
+- **Discord DM reminders** — reminders now fire correctly in Discord direct-message channels ([#1609](https://github.com/netclaw-dev/netclaw/pull/1609))
+- **Slack processing-status updates serialized** — concurrent status updates on a Slack thread no longer race ([#1556](https://github.com/netclaw-dev/netclaw/pull/1556))
+- **CLI model picker preserves hand-set modalities** — re-setting a model via `netclaw model set` or the picker no longer discards manually-configured input modalities ([#1610](https://github.com/netclaw-dev/netclaw/pull/1610))
+
+### Dependency Updates
+- ModelContextProtocol versioning consolidated into the central props file ([#1614](https://github.com/netclaw-dev/netclaw/pull/1614))
+- MessagePack 3.1.7 → 3.1.8 ([#1605](https://github.com/netclaw-dev/netclaw/pull/1605))
+- .NET SDK 10.0.300 → 10.0.301 ([#1381](https://github.com/netclaw-dev/netclaw/pull/1381))
+
 ## 0.25.0-alpha.onnx.4 (2026-07-09)
 
 > **Experimental feature build** (fourth in the memory-embeddings series). Same gating: