feat(headless): typed --console option resolution + command-line flag

Adds the first piece of the interactive headless console (docs/plans/
2026-09-07-headless-console.md): HeadlessConsoleOptions.Resolve picks
--console, then ACDREAM_HEADLESS_CONSOLE=1, then a terminal-shaped
default, matching the project's typed-options-object convention rather
than a scattered env-var read. HeadlessCommandLine.Parse now accepts
--console as a bare flag (no value token) alongside the existing
paired options. Both new launch-options.md rows are added in this
commit per LaunchOptionsDocumentationTests' bidirectional rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/AcDream.Headless/Configuration/HeadlessCommandLine.cs

@@ -4,7 +4,8 @@ internal sealed record HeadlessCommandLine(
     string Command,
     string ConfigurationPath,
     HeadlessPathOverrides Paths,
-    HeadlessDirectCredentials? DirectCredentials)
+    HeadlessDirectCredentials? DirectCredentials,
+    bool Console = false)
 {
     internal static HeadlessCommandLine Parse(
         IReadOnlyList<string> arguments)
@@ -23,15 +24,26 @@ internal sealed record HeadlessCommandLine(
         string? cacheDirectory = null;
         string? user = null;
         string? password = null;
-        for (int index = 1; index < arguments.Count; index += 2)
+        bool console = false;
+        int index = 1;
+        while (index < arguments.Count)
         {
+            string name = arguments[index];
+            // --console is a bare flag (no value token) — the interactive
+            // console for the run command (see HeadlessConsoleOptions).
+            if (name == "--console")
+            {
+                console = true;
+                index += 1;
+                continue;
+            }
+
             if (index + 1 >= arguments.Count)
             {
                 throw new HeadlessCommandLineException(
                     "Every command option requires a value.");
             }
 
-            string name = arguments[index];
             string value = arguments[index + 1];
             if (string.IsNullOrWhiteSpace(value))
             {
@@ -65,6 +77,7 @@ internal sealed record HeadlessCommandLine(
                     throw new HeadlessCommandLineException(
                         "Unknown command option.");
             }
+            index += 2;
         }
 
         if (configurationPath is null)
@@ -92,7 +105,8 @@ internal sealed record HeadlessCommandLine(
                 cacheDirectory),
             user is null
                 ? null
-                : new HeadlessDirectCredentials(user, password!));
+                : new HeadlessDirectCredentials(user, password!),
+            console);
     }
 
     private static void SetOnce(ref string? destination, string value)

src/AcDream.Headless/Configuration/HeadlessConsoleOptions.cs

@@ -0,0 +1,38 @@
+namespace AcDream.Headless.Configuration;
+
+/// <summary>
+/// Typed resolution for the headless interactive console (docs/plans/
+/// 2026-09-07-headless-console.md). Three inputs, first match wins:
+/// the <c>--console</c> command-line flag, the
+/// <c>ACDREAM_HEADLESS_CONSOLE=1</c> environment variable, and finally a
+/// terminal-shaped default — on when stdin is a real console (an operator
+/// typing at a keyboard), off when it is redirected (a script, CI runner, or
+/// piped fixture, where a background reader thread blocked on
+/// <c>ReadLine</c> would never see input and would just sit idle). See
+/// docs/launch-options.md for the documented row this owns.
+/// </summary>
+internal static class HeadlessConsoleOptions
+{
+    internal const string EnvironmentVariable = "ACDREAM_HEADLESS_CONSOLE";
+
+    internal static bool Resolve(
+        bool commandLineFlag,
+        bool standardInputIsTerminal) =>
+        Resolve(
+            commandLineFlag,
+            Environment.GetEnvironmentVariable,
+            standardInputIsTerminal);
+
+    internal static bool Resolve(
+        bool commandLineFlag,
+        Func<string, string?> environment,
+        bool standardInputIsTerminal)
+    {
+        ArgumentNullException.ThrowIfNull(environment);
+        if (commandLineFlag)
+            return true;
+        if (environment(EnvironmentVariable) == "1")
+            return true;
+        return standardInputIsTerminal;
+    }
+}