bug(dsh): handle Scope failures at tool and command boundaries

[knqiufan]

Describe the bug

Parent tracking issue: #1450, work package A.

The DSH plugin resolves the Server-owned Scope before entering its direct-operation error boundary. A failure from POST /v1/scope-bindings/resolve therefore rejects a registered pc_* tool or /pc command instead of returning a controlled failure.

The same unconditional prerequisite blocks /pc doctor, /pc capabilities, bare /pc, and even local usage errors. In particular, Doctor cannot reach its health checks when Scope resolution is the failing layer.

After Scope resolution succeeds, direct HTTP 404 responses are normalized to code: not_found, but their specific public error code, such as memory_not_found, is discarded.

Steps to reproduce

Use the current DSH plugin's registered tool/command handlers with its real PowerContextClient and a controlled fetch fixture:

1. Return HTTP 404 with {"detail":"Not Found"} for /v1/scope-bindings/resolve; return valid successful JSON for health and capabilities.
2. Execute registered pc_search, /pc doctor, /pc capabilities, bare /pc, or an unknown /pc subcommand.
3. Observe that each rejects with PowerContext Server returned HTTP 404, and that the health/capability routes are never reached.
4. Repeat with a valid Scope-domain response: HTTP 404 and {"error":{"code":"scope_not_found","message":"The requested Scope was not found."}}. It still escapes the registered entrypoint.
5. Return a valid Scope from the resolver, then return a Memory-domain 404 from the requested operation. The result is controlled, but contains only code: not_found, without the specific memory_not_found code.

A real-Server acceptance case should also use a nonexistent explicit Scope: scoped operations must fail without falling back to the Server default, while health and capability inspection remain usable.

Expected behavior

• Registered tools and commands contain failures across Scope resolution and operation execution; no uncaught host exception or false success.
• Preserve existing error classifications and add optional error_code for recognized public 404 domain codes. Keep existing specific 409/422 codes compatible.
• A code-less 404 from an explicitly required endpoint is distinguishable from a valid resource/domain 404. A 404 alone must not be presented as proof of a wrong process or deployment version.
• /pc doctor, /pc capabilities, unknown commands, and usage validation do not require Scope resolution.
• Bare /pc remains inspectable when Scope resolution fails, reporting unresolved Scope and controlled recovery information.
• Other scoped operations retain Server-owned explicit/binding/default precedence. Scope failure or cancellation must not trigger a later write, new binding, or fallback to another Scope.
• Propagate the caller's cancellation signal through Scope resolution without changing timeout budgets or introducing retries.
• Reuse existing content-free native diagnostics and deduplication. Diagnostic delivery failures must not escape the operation boundary. Do not echo Server messages, URLs, credentials, or response bodies.

Actual behavior

The source-level reproduction rejects at Scope resolution for all entrypoints listed above. A successful Scope resolution followed by a Memory 404 returns {ok:false,code:"not_found",status:404,...} without its domain code.

The existing five focused test files for tools, commands, invocation, Scope, and diagnostics pass all 23 tests, so the regression needs coverage through actual registered entrypoints rather than only direct calls to the lower-level invocation helper.

Environment

• PowerContext source: master at f0f288a.
• DSH plugin: integrations/dsh/plugins/powercontext.
• Reproduction: Node.js 24.14.1 on Windows, using registered handlers and controlled HTTP responses.
• Evidence is a source-level reproduction. The exact deployed endpoint, plugin revision, and DSH version from the original user report remain unverified.

Additional context

Relevant source: tool entrypoint, command entrypoint, and error mapping.

Reuse #1401's Scope contract and #1360's diagnostic infrastructure. #1438 owns HTTP request encoding changes; #1398 owns access-control behavior. #1449's default-Scope onboarding is independent.

This issue excludes automatic hook diagnostic wiring and snapshots, expanded CLI Doctor probes, the full status panel, and guidance changes; those remain in #1450 B–F. Include focused regression tests, one real-Server DSH acceptance case, maintained English/Chinese documentation, and rebuilt checked-in plugin artifacts.

AI assistance: OpenAI Codex assisted with source inspection, reproduction, and this report.

Are you willing to submit a PR to fix this bug?

• Yes, I would like to submit a PR.