fix(daemon): prevent graceful shutdown hang

Author: lxhtt

MCServerLauncher.Daemon/GracefulShutdown.cs

@@ -4,8 +4,9 @@ namespace MCServerLauncher.Daemon;
 
 public class GracefulShutdown : IDisposable
 {
-    private readonly SemaphoreSlim _semaphore = new(0);
     private readonly CancellationTokenSource _source = new();
+    private readonly TaskCompletionSource _shutdownSignal =
+        new(TaskCreationOptions.RunContinuationsAsynchronously);
     private bool _isDisposed;
 
     public GracefulShutdown()
@@ -35,18 +36,24 @@ public void Dispose()
 
     public async Task Shutdown()
     {
-        if (_source.IsCancellationRequested)
-            throw new InvalidOperationException("Already shutdown");
+        if (_source.IsCancellationRequested) return;
 
         await _source.CancelAsync();
+        _shutdownSignal.TrySetResult();
         Log.Information("[GracefulShutdown] shutting down...");
         if (OnShutdown is not null) await OnShutdown.Invoke();
-        _semaphore.Release();
     }
 
     public async Task WaitForShutdownAsync(int timeout = -1)
     {
-        await _semaphore.WaitAsync(timeout);
+        var waitTask = _shutdownSignal.Task;
+        if (timeout < 0)
+        {
+            await waitTask;
+            return;
+        }
+
+        await waitTask.WaitAsync(TimeSpan.FromMilliseconds(timeout));
     }
 
     private void Dispose(bool dispose)
@@ -60,4 +67,4 @@ private void Dispose(bool dispose)
     {
         Dispose(false);
     }
-}
+}

MCServerLauncher.ProtocolTests/GracefulShutdownTests.cs

@@ -0,0 +1,43 @@
+using MCServerLauncher.Daemon;
+
+namespace MCServerLauncher.ProtocolTests;
+
+public class GracefulShutdownTests
+{
+    [Fact]
+    [Trait("Category", "Daemon")]
+    [Trait("Category", "Shutdown")]
+    public async Task WaitForShutdownAsync_CompletesBeforeBlockedShutdownCallbacksFinish()
+    {
+        using var gracefulShutdown = new GracefulShutdown();
+        var callbackCanFinish = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+        var callbackStarted = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        gracefulShutdown.OnShutdown += async () =>
+        {
+            callbackStarted.SetResult();
+            await callbackCanFinish.Task;
+        };
+
+        var shutdownTask = gracefulShutdown.Shutdown();
+        await callbackStarted.Task.WaitAsync(TimeSpan.FromSeconds(2));
+
+        await gracefulShutdown.WaitForShutdownAsync().WaitAsync(TimeSpan.FromMilliseconds(200));
+
+        callbackCanFinish.SetResult();
+        await shutdownTask.WaitAsync(TimeSpan.FromSeconds(2));
+    }
+
+    [Fact]
+    [Trait("Category", "Daemon")]
+    [Trait("Category", "Shutdown")]
+    public async Task Shutdown_CalledMoreThanOnce_DoesNotThrow()
+    {
+        using var gracefulShutdown = new GracefulShutdown();
+
+        await gracefulShutdown.Shutdown();
+        await gracefulShutdown.Shutdown();
+
+        await gracefulShutdown.WaitForShutdownAsync().WaitAsync(TimeSpan.FromMilliseconds(200));
+    }
+}

docs/superpowers/plans/2026-06-19-daemon-api-doc-log-hint.md

@@ -0,0 +1,38 @@
+# Daemon API doc log hint implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Print the Postman collection URL when the daemon starts.
+
+**Architecture:** Keep the existing startup log style in `Application.ServeAsync`. Add one information log line after the HTTP server line that points to `/postman_collection.json`.
+
+**Tech Stack:** C# 14, .NET 10, Serilog, TouchSocket HTTP.
+
+---
+
+## Touched areas
+
+- `backend`
+- `docs`
+- `tests`
+
+## Tasks
+
+### Task 1: Test
+
+- [x] Add a protocol test requiring the daemon startup log to mention `/postman_collection.json`.
+
+### Task 2: Implementation
+
+- [x] Add the startup log line in `Application.ServeAsync`.
+
+### Task 3: Verify
+
+- [x] Run the focused inbound test.
+- [x] Build daemon.
+- [x] Run diff whitespace check.
+
+## Changelog
+
+- 2026-06-19: Planned startup log hint for the Postman API documentation URL.
+- 2026-06-19: Added the startup API docs log line and verified the Postman collection remains complete.

docs/superpowers/plans/2026-06-19-daemon-api-doc-log.md

@@ -0,0 +1,37 @@
+# Daemon API docs startup log implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Print the Postman collection URL when the daemon starts.
+
+**Architecture:** Keep the existing WebSocket and HTTP startup logs. Add one adjacent log line that points to `/postman_collection.json`, the only machine-readable API documentation artifact.
+
+**Tech Stack:** C# 14, .NET 10, Serilog, protocol tests.
+
+---
+
+## Touched areas
+
+- `backend`
+- `docs`
+- `tests`
+
+## Tasks
+
+### Task 1: Lock log expectation
+
+- [ ] Add a source-inspection protocol test requiring the startup log to mention `/postman_collection.json`.
+
+### Task 2: Add log line
+
+- [ ] Add `Log.Information` after the HTTP server startup log.
+
+### Task 3: Verify
+
+- [ ] Run focused inbound tests.
+- [ ] Build daemon.
+- [ ] Run `git diff --check`.
+
+## Changelog
+
+- 2026-06-19: Planned a daemon startup log line for the Postman API documentation URL.

docs/superpowers/plans/2026-06-19-daemon-embedded-swagger.md

@@ -0,0 +1,75 @@
+# Daemon Embedded Swagger Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Embed the current protocol OpenAPI and related protocol docs into the daemon and expose an offline Swagger UI over the existing TouchSocket HTTP plugin.
+
+**Architecture:** The daemon keeps using TouchSocket `HttpPlugin`; no ASP.NET Core or Swashbuckle pipeline is introduced. Protocol docs and Swagger UI files are packaged as `EmbeddedResource` items and served through explicit `GET` routes.
+
+**Tech Stack:** C# 14, .NET 10, TouchSocket HTTP, embedded resources, Swagger UI static assets.
+
+---
+
+## Touched Areas
+
+- `docs`
+- `agent-docs`
+- `protocol`
+- `backend`
+- `tests`
+
+## Tasks
+
+### Task 1: Lock Embedded Documentation Expectations
+
+**Files:**
+- Modify: `MCServerLauncher.ProtocolTests/DaemonInboundTransportPipelineTests.cs`
+
+- [x] Add source/resource tests that require:
+  - `openapi.json` to be embedded in `MCServerLauncher.Daemon`.
+  - Swagger UI static files to be embedded.
+  - `HttpPlugin` to expose `/openapi.json`, `/swagger`, `/swagger/index.html`, and `/docs/protocol/...`.
+
+### Task 2: Add Embedded Protocol And Swagger Assets
+
+**Files:**
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/openapi.json`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/protocol/topics/*.md`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/swagger/index.html`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/swagger/swagger-ui.css`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/swagger/swagger-ui-bundle.js`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/swagger/swagger-ui-standalone-preset.js`
+- Create: `MCServerLauncher.Daemon/.Resources/Docs/swagger/LICENSE`
+- Modify: `MCServerLauncher.Daemon/MCServerLauncher.Daemon.csproj`
+
+- [x] Copy the current `mcsl-future-protocol` OpenAPI and topic docs into daemon resources.
+- [x] Add local Swagger UI assets so `/swagger` works without internet access.
+- [x] Embed docs with stable logical names under `MCServerLauncher.Daemon.Resources.Docs.*`.
+
+### Task 3: Serve Embedded Documentation
+
+**Files:**
+- Create: `MCServerLauncher.Daemon/Remote/EmbeddedDocumentation.cs`
+- Modify: `MCServerLauncher.Daemon/Remote/HttpPlugin.cs`
+
+- [x] Add a small helper that maps request paths to embedded documentation resources and content types.
+- [x] Serve `/openapi.json`.
+- [x] Serve `/swagger` and `/swagger/index.html`.
+- [x] Serve `/swagger/*` static assets.
+- [x] Serve `/docs/protocol/*` Markdown resources.
+- [x] Keep existing `/`, `/info`, and `/subtoken` behavior unchanged.
+
+### Task 4: Verify
+
+**Commands:**
+- [x] `dotnet test MCServerLauncher.ProtocolTests/MCServerLauncher.ProtocolTests.csproj --filter FullyQualifiedName~DaemonInboundTransportPipelineTests /m:1`
+- [x] `dotnet build MCServerLauncher.Daemon/MCServerLauncher.Daemon.csproj /m:1`
+- [x] `python3 -m json.tool MCServerLauncher.Daemon/.Resources/Docs/openapi.json >/tmp/mcsl-daemon-openapi.json`
+- [x] `git diff --check`
+
+## Changelog
+
+- Added plan for embedding protocol docs and offline Swagger UI in the daemon.
+- Embedded `openapi.json`, protocol topic Markdown, and offline Swagger UI assets in the daemon.
+- Added TouchSocket HTTP routes for `/openapi.json`, `/swagger`, `/swagger/index.html`, `/swagger/*`, and `/docs/protocol/*`.
+- Added protocol tests that lock resource embedding and route registration expectations.

docs/superpowers/plans/2026-06-19-graceful-shutdown-hang.md

@@ -0,0 +1,51 @@
+# Graceful Shutdown Hang Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Prevent daemon shutdown from hanging when shutdown callbacks wait on work that is also waiting for the shutdown signal.
+
+**Architecture:** `GracefulShutdown.Shutdown()` should be idempotent and publish the shutdown signal before awaiting registered cleanup callbacks. `WaitForShutdownAsync()` should observe already-completed shutdowns and should not rely on a single semaphore release that can be lost or delayed by callbacks.
+
+**Tech Stack:** C# 14, .NET 10, xUnit protocol tests.
+
+---
+
+### Task 1: Fix GracefulShutdown Signal Ordering
+
+**Files:**
+- Create: `MCServerLauncher.ProtocolTests/GracefulShutdownTests.cs`
+- Modify: `MCServerLauncher.Daemon/GracefulShutdown.cs`
+
+- [x] **Step 1: Write the failing tests**
+
+Add tests proving:
+
+- `WaitForShutdownAsync()` completes even when an `OnShutdown` callback is still blocked.
+- Calling `Shutdown()` more than once is harmless and does not throw.
+
+- [x] **Step 2: Run focused tests and verify red**
+
+Run: `dotnet test MCServerLauncher.ProtocolTests/MCServerLauncher.ProtocolTests.csproj --filter GracefulShutdownTests /m:1`
+
+Expected before implementation: callback-order test fails because `WaitForShutdownAsync()` waits behind `OnShutdown`.
+
+- [x] **Step 3: Implement minimal fix**
+
+Use a `TaskCompletionSource` as the shutdown signal, set it before invoking callbacks, and make repeat `Shutdown()` calls return without throwing.
+
+- [x] **Step 4: Verify**
+
+Run:
+
+```bash
+dotnet test MCServerLauncher.ProtocolTests/MCServerLauncher.ProtocolTests.csproj --filter GracefulShutdownTests /m:1
+dotnet test MCServerLauncher.ProtocolTests/MCServerLauncher.ProtocolTests.csproj /m:1
+git diff --check
+```
+
+Result: focused `GracefulShutdownTests` passed, full protocol tests passed with 343/343 tests, and whitespace check passed.
+
+## Changelog
+
+- 2026-06-19: Planned shutdown signal ordering fix for daemon `GracefulShutdown`.
+- 2026-06-19: Fixed shutdown wait ordering by publishing the shutdown signal before awaiting callbacks and making repeated shutdown requests harmless.

docs/superpowers/plans/2026-06-19-migrate-to-apifox-skill.md

@@ -0,0 +1,76 @@
+# Migrate To Apifox Skill Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Create a personal agent skill for migrating API documentation from project source code, OpenAPI, Postman, or Swagger into Apifox project JSON.
+
+**Architecture:** The skill lives under `/Users/lxhtt/.agents/skills/migrate-to-apifox`. `SKILL.md` gives the workflow and trigger rules, `APIFOX_FORMAT.md` records the observed Apifox project shape from `/Users/lxhtt/Downloads/schema-test.apifox.json`, and `scripts/validate-apifox.js` performs deterministic structure checks.
+
+**Tech Stack:** Markdown skill instructions, Apifox project JSON, Node.js validation script using only built-in modules.
+
+---
+
+### Task 1: Skill instructions and format reference
+
+**Files:**
+- Create: `/Users/lxhtt/.agents/skills/migrate-to-apifox/SKILL.md`
+- Create: `/Users/lxhtt/.agents/skills/migrate-to-apifox/APIFOX_FORMAT.md`
+- Create: `/Users/lxhtt/.agents/skills/migrate-to-apifox/scripts/validate-apifox.js`
+
+- [x] **Step 1: Inspect Apifox sample**
+
+Run:
+
+```bash
+python3 -m json.tool /Users/lxhtt/Downloads/schema-test.apifox.json >/tmp/schema-test.pretty.json
+```
+
+Expected: command exits 0 and reveals root collections such as `apiCollection`, `webSocketCollection`, and `schemaCollection`.
+
+- [x] **Step 2: Write `SKILL.md`**
+
+Include triggers for Apifox migration, source-code extraction, OpenAPI, Swagger, and Postman conversion. Keep the file under 100 lines and link to `APIFOX_FORMAT.md`.
+
+- [x] **Step 3: Write `APIFOX_FORMAT.md`**
+
+Document the project root shape, HTTP API item shape, WebSocket API item shape, schema item shape, and migration rules that prevent WebSocket APIs from being represented as HTTP `GET`.
+
+- [x] **Step 4: Write validation script**
+
+Create `scripts/validate-apifox.js` with checks for:
+
+- root `$schema.app === "apifox"`
+- at least one of `apiCollection`, `webSocketCollection`, or `schemaCollection`
+- HTTP APIs have lowercase `method`; `api.type` may be omitted in Apifox samples and defaults to HTTP
+- webhook items under `apiCollection` are accepted with `api.type === "webhook"`
+- WebSocket APIs have no `method`; `api.type` may be omitted in Apifox samples or set to `websocket`
+- schema items carry `schema.jsonSchema`
+
+- [x] **Step 5: Validate the skill artifacts**
+
+Run:
+
+```bash
+node /Users/lxhtt/.agents/skills/migrate-to-apifox/scripts/validate-apifox.js /Users/lxhtt/Downloads/schema-test.apifox.json
+node /Users/lxhtt/.agents/skills/migrate-to-apifox/scripts/validate-apifox.js MCServerLauncher.Daemon/.Resources/Docs/apifox.json
+python3 - <<'PY'
+from pathlib import Path
+p = Path('/Users/lxhtt/.agents/skills/migrate-to-apifox/SKILL.md')
+print(len(p.read_text().splitlines()))
+PY
+git diff --check
+```
+
+Expected: validation commands exit 0, `SKILL.md` stays below 100 lines, and `git diff --check` exits 0.
+
+## Changelog
+
+- Created this plan for the `migrate-to-apifox` personal skill.
+- Added `migrate-to-apifox` with a concise `SKILL.md`, an Apifox format reference, and a Node.js validation script.
+- Validated the script against `/Users/lxhtt/Downloads/schema-test.apifox.json` and `MCServerLauncher.Daemon/.Resources/Docs/apifox.json`.
+- Expanded the skill from a narrow HTTP/WebSocket/schema migration helper into a full Apifox project migration skill covering raw socket services, Socket.IO, MCP, custom endpoint protocols, reusable components, auth, tests, and environments.
+- Added strict native validation after Apifox imported a generated daemon project with zero recognized APIs. The fix aligns WebSocket items with Apifox's native export shape by omitting `api.type`, while still forbidding `api.method`, and checks HTTP API metadata required by native project imports.
+- Updated the daemon Apifox export to match `/Users/lxhtt/Downloads/pingws.json`: WebSocket APIs are nested under `根目录 -> WebSocket actions`, payloads are stored in `api.requestBody.message`, and `api.parameters` carries query/path/cookie/header buckets.
+- Updated the daemon Apifox export and skill rules so WebSocket action `api.path` no longer embeds `{{wsUrl}}?token={{token}}`; the environment owns the WebSocket base URL and `token` is documented in `api.parameters.query`.
+- Updated dynamic value and native-variable rules: WebSocket request IDs use Apifox dynamic values such as `{{$string.uuid}}`, environment/global variables use native `name` fields, and shared daemon token auth lives in root `commonParameters.parameters.query`.
+- Updated daemon Apifox guidance so the project homepage explains how to obtain MainToken, `globalVariables` no longer duplicates `baseUrl` or `wsUrl`, environment variables no longer carry `token`, `permissions`, or `expires`, and users are directed to edit environment management -> global parameters -> Query -> `token`.