Tracking Issue: DSH reliability and cross-Agent PowerContext guidance

[knqiufan]

Feature description

Make the DSH installation-to-recall journey diagnosable and make PowerContext tool/Skill routing consistent across maintained Agent integrations.

This is a focused follow-up tracker for a reported user journey: install the plugin, connect to a compatible Server, observe automatic recall/capture, and use natural-language Memory or Handoff requests correctly. It records independently deliverable work and acceptance criteria. Child Issues should own implementation and closure.

Problem and proposed solution

Reported user experience

A PowerContext 0.1.0 user reported that:

1. The DSH plugin loaded and exposed pc_* tools, but calls returned Error: PowerContext Server returned HTTP 404.
2. Automatic recall, capture, and injection were not apparent in the conversation, leading the user to suspect that the hook was not registered.
3. Tool descriptions and Skill discovery gave weak guidance. In the reported interaction, the Agent started with pc_memory_list as if listing stored entries were the normal way to restore context.

The user suggested a using-powercontext routing Skill with more focused domain Skills. This is useful as an additional guidance layer, while per-tool descriptions remain necessary because an Agent can call an exposed tool without loading a Skill.

Evidence boundary: these are reported symptoms, supplemented by source inspection. The original failing endpoint, response body, installed plugin revision, and exact DSH version have not been captured here. A wrong endpoint, proxy/base-path configuration, or mismatched Server/plugin revision are possibilities; the status code alone does not establish which occurred. An empty Memory store is also different from a missing HTTP route.

Verified current gaps

Source baseline: PowerContext master f0f288a, inspected on 2026-09-04. Released 0.1.0 and current master must be qualified separately.

Area	Current behavior and consequence
Error boundary	Tool execution and the registered command handler resolve Scope before entering the operation error boundary. Scope failures can escape as host tool errors. Even /pc doctor depends on successful Scope resolution before it reaches its health checks.
404 interpretation	Direct operation mapping maps every HTTP 404 to not_found. Diagnosis must distinguish required-route failures from valid missing-resource/domain results using operation context and typed errors.
Automatic path	Scope resolution in recall can fail into a silent catch before prepare/capture diagnostics run. Successful/empty prepare results go to debug logging; injected context has no structured snapshot presentation metadata.
Installation diagnostics	doctor dsh checks CLI availability and plugin registration, not the endpoint actually used by the running plugin. The DSH guide leads with --ref master and lacks a complete adjacent, release-matched startup journey.
Guidance	Tool descriptions do not clearly distinguish inventory from contextual search. The Skill registration and system guidance provide limited routing. Some candidate-generation tools already mention human approval; those safeguards should be retained and made consistent.

Preserve the existing contracts

• Automatic hooks remain responsible for bounded recall and prompt capture. Manual tools supplement that path when the user explicitly requests an operation or needs additional retrieval. Guidance must not claim recall succeeded merely because a hook is configured.
• Explicit “remember/save this” and “search my memories” requests require the corresponding tool and honest reporting of its result. Automatic Source capture is not an explicit Memory write. Ordinary coding prompts must not trigger redundant remember, list, or search calls.
• Preserve the existing plugin diagnostics contract: typed classification, domain errors handled first, content-free diagnostics, bounded presentation, and the supported host channel. DSH currently uses the plugin logger. Diagnostic failures must not break normal Agent work.
• Do not inject a failure form: notice message into model context. That conflicts with the current diagnostics contract. Any additional DSH UI channel needs an explicit presentation decision and, if it changes that contract, design review first. Snapshot metadata may describe real recalled content; it must not fabricate successful recall.
• Diagnostic events and model-facing failures must not contain raw endpoint URLs, credentials, request/response bodies, or user content. An explicit local Doctor/status surface should identify the effective configuration through appropriately redacted output.
• Preserve Scope isolation, exact citations, untrusted historical evidence, and human-controlled candidate approval. Listing or generating a candidate does not approve, publish, install, or execute it.

Proposed child Issues

Work packages A, B, and C have linked implementation Issues and merged PRs below. D is implemented in #1522 and ready for review; it is not merged. E and F remain proposed work packages awaiting their own Issue links and ownership. Each child should include a focused reproduction/scenario, scope, acceptance, documentation, and validation; normally one implementation PR, with a second host-projection PR when needed.

• bug(dsh): handle Scope failures at tool and command boundaries #1451 — A — bug(dsh): handle Scope failures at tool and command boundaries — delivered by fix(dsh): handle Scope failures at tool and command boundaries #1452
  First priority: normalize failures from Scope resolution and direct execution, preserve domain semantics, and make health/status commands usable when Scope resolution fails. Acceptance: a required-route 404, a valid resource/domain 404, authentication failure, timeout, and unresolved Scope produce distinct, actionable outcomes without an uncaught host exception or a false success. Do not create or change Scope bindings as a diagnostic side effect.

• bug(dsh): complete automatic-path diagnostics and recall presentation #1457 — B — bug(dsh): complete automatic-path diagnostics and recall presentation — delivered by fix(dsh): complete automatic-path diagnostics and recall presentation #1459
  First priority: connect the missing Scope failure exit to the existing diagnostic mechanism and verify where a DSH user can inspect it. Add supported structured snapshot metadata for actual recalled content. Acceptance: a failed automatic path continues normal Agent work and emits a bounded, content-free diagnostic; an empty result remains normal; successful recall is inspectable without injecting it twice. Preserve independent capture after a preparation failure when Scope is valid. A new diagnostic UI channel remains subject to the contract decision above.

• feat(dsh): diagnose effective Server configuration and document matched setup #1493 — C — feat(dsh): diagnose the effective Server configuration and document matched setup — delivered by feat(dsh): diagnose effective Server configuration and matched setup #1494 (merged on 2026-09-09)
  First priority: complete the DSH-specific release/master setup and Server startup instructions on top of docs: separate released and unreleased install paths #1448. Extend diagnostics to distinguish registration, liveness, readiness, required-route compatibility, and Scope availability. Use the running plugin's resolved configuration for in-host checks; standalone CLI checks must report when they cannot observe the running host's overrides instead of claiming equivalence. Acceptance: a version-matched clean setup with a working Memory-processing configuration and a known fixture reaches usable recall; wrong-route, unreachable, unready, and unscoped cases identify the failing layer. A healthy Server without inference models may correctly return empty recall. Doctor remains read-only and reuses existing service/health diagnostics.

• feat(integrations): align PowerContext system guidance and tool routing #1520 — D — feat(integrations): align PowerContext system guidance and tool routing — feat(integrations): align agent guidance and tool routing #1522 is ready for review; not merged
  Guidance priority: give each exposed operation concise product/domain context, positive triggers, relevant exclusions, and constraints. Distinguish list for inventory from search for relevant prior context; avoid routine per-turn calls while preserving explicit user requests. Define common semantics with host-specific names and capabilities. Coordinate canonical content and projections with Tracking Issue: deterministic Agent distributions from one canonical plugin #1405 / docs(rfc): define deterministic agent plugin distributions #1410; this child owns guidance behavior, not another distribution generator. Acceptance: DSH and each migrated host expose the intended guidance, unsupported operations are not advertised, and scenario evaluation shows correct routing with the Skill both loaded and unloaded.

• E — feat(integrations): add layered PowerContext Skill routing
  Guidance priority: propose using-powercontext as a small router and Memory, Handoff, and Review domain Skills for detailed workflows. Put discoverable English/Chinese intents in the actual host-visible name/description rather than relying only on provider metadata such as DSH whenToUse. Build on the explicit-memory behavior delivered by fix(codex): make explicit memory requests trigger the project-context skill #1378 / fix(codex): route explicit memory requests #1436. Resolve canonical naming, packaging, and the project-context compatibility/migration path through Tracking Issue: deterministic Agent distributions from one canonical plugin #1405 / docs(rfc): define deterministic agent plugin distributions #1410 before reorganizing distributions. Acceptance: ordinary coding needs no PowerContext Skill/tool detour; explicit memory requests call the correct operation; Handoff and Review route correctly without granting new authority. Do not require loading a Skill before every response.

• F — feat(dsh): expose bounded recall and capture status through /pc
  Follow-up priority: show independently observed prepare/capture outcomes, freshness, and useful recovery guidance in an explicit status view. Acceptance: users can distinguish ready, empty, skipped, unavailable, and not yet observed; stale results are identified; no status claims a write or injection occurred without evidence. Store only bounded operational state. The status view remains available when Scope resolution fails.

Sequence and existing ownership

A, B, and C are complete on master. D's implementation and qualification evidence are in #1522, now ready for review; D remains unchecked until its delivery is merged and accepted. The PR distinguishes first-turn routing scores from multi-turn Handoff validation and retains measured model limitations. E follows agreement on D's routing semantics and the canonical-source compatibility decisions. F consumes the outcomes established by A–C. Merged master support does not by itself establish availability in a released package.

Existing work	Relationship
#1352, #1338, and the manifest delivered by #1357	Product roadmap, capability alignment, and per-host availability remain there. Use integrations/capabilities.toml to enumerate qualification targets.
#1405 / #1410	Own canonical plugin source, naming, generated distributions, migration, and drift prevention. This tracker supplies guidance requirements and acceptance evidence. The RFC PR is currently open.
#1406 / #1408	Own future immutable release installers. C improves the current DSH journey without replacing that architecture; the RFC PR is currently open.
#1298 / #1360 / #1361	Established service and plugin-diagnostic work. A–C close specific DSH integration gaps rather than recreate the service layer or common diagnostic system.
#1370 and #1378 / #1436	Required DSH service registration and explicit Codex Memory routing are already addressed. Preserve them as baseline behavior.
#1448	Root README release/master separation and the powercontext-v0.1.0 ref correction are already merged; only remaining DSH-specific gaps belong here.
#1362 and #1449	New lifecycle coverage and first-start Scope/Dashboard onboarding remain separately owned. This tracker does not redefine lifecycle events or default Scope creation.

Tool-count reduction, DSH/MCP parity, Handoff read/edit classification, and approval behavior without an interactive channel need separate design decisions. A settings card, DSH peer/type baseline updates, and release-version hygiene can become independent follow-ups after concrete gaps are verified; they do not block the reliability fixes. Public API, compatibility, or substantial architecture changes follow the RFC process.

Validation and completion

Children should protect observable behavior rather than exact prose, arbitrary keyword counts, internal call order, or a fixed number of tools.

Required acceptance evidence:

1. A clean, version-matched DSH setup captures a known Source. With the required Memory-processing configuration and a deterministic fixture, it produces Memory and recalls the expected context in a subsequent session using the same intended Scope. Verify capture, processing, and recall separately; a valid empty result remains a successful diagnosed state.
2. Route mismatch, domain absence, authentication failure, timeout, empty recall, and missing Scope remain distinguishable; diagnostics/status work during failure and never turn failure into saved Memory or injected context.
3. English and Chinese scenarios cover ordinary coding, continuing prior work, explicit remember/search, inventory, Handoff, candidate review, and unavailable tools. Record host/model/configuration, the baseline failure, actual calls/results, and evaluation limits. Description keywords alone do not establish reliable Agent behavior.
4. Exact citations, Scope isolation, explicit-write semantics, human Review boundaries, bounded injection, and diagnostic redaction remain intact.

Relevant commands for child work, as applicable:

pnpm --dir integrations/dsh/plugins/powercontext test
pnpm --dir integrations/dsh/plugins/powercontext run test:e2e
uv run pytest tests/test_dsh_cli.py tests/e2e/test_dsh_http_chain.py -q
make docs-test

Use each affected host's own checks. If the OpenAPI contract changes, edit openapi/powercontext.yaml, regenerate with make api-generate, and run make contract-test; do not hand-edit generated clients.

Close this tracker when A–F have linked delivery and acceptance evidence for their agreed host/version scope. Any deferred work must have an explicit disposition and an independent Issue where appropriate; it must not be marked delivered. Released and master-only support must remain distinguishable. Child PRs should close their child Issue and reference this tracker rather than close the entire tracker.

Alternatives considered

• Only expand tool descriptions: improves immediate selection but leaves failure diagnosis, workflow detail, and cross-host drift unresolved.
• Only add a router Skill: insufficient when a model calls an already-visible tool without loading the Skill.
• Only fix Server connectivity: necessary, but leaves redundant inventory/search and misleading explicit-memory acknowledgements possible.
• Combine everything in one implementation Issue/PR: couples urgent fixes to packaging and Skill design. Independent children keep acceptance and delivery bounded.

Additional context

This proposal is based on the reported user experience and current source/contract inspection. It does not claim an end-to-end reproduction of the original user's environment or completed Agent-routing evaluations. Child Issues should capture exact versions and sanitized reproduction evidence before asserting a specific deployment root cause.

AI assistance: OpenAI Codex assisted with source inspection, existing-Issue reconciliation, and preparation of this proposal.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.

[knqiufan]

Alignment for D/E: system guidance, tool descriptions, and task-specific Skills

Follow-up user screenshots from DSH's creation mode provide a useful concrete reference for work packages D and E. The cordis_* entries shown under Tool definitions are tools; the inspected source separately provides task Skills such as cordis-plugin-development. Their value is the coordination between three model-visible surfaces:

Surface	Responsibility
System guidance	Explain how the capability relates to the current Agent and task, its scope and limits, and which operation or available Skill matches the request.
Tool description	Explain one operation's purpose, prerequisites, result meanings, and essential follow-up constraints sufficiently for correct tool selection.
Skill	Supply the detailed workflow, examples, and troubleshooting when the task needs them.

Source reference: DeepSeek Harness commit 76fda729, including the Cordis system guidance, cordis_run description, and development Skill.

Proposed refinement to D

Use the child title feat(integrations): align PowerContext system guidance and tool routing, and explicitly include the existing host system-guidance surface in its deliverables.

• Explain PowerContext's relationship to the Agent: durable project history and handoff across sessions, Server-owned Scope selection, and historical evidence subordinate to current instructions.
• Describe automatic recall/capture and explicit operations separately. Automatic processing is an attempted capability, not proof that retrieval or persistence succeeded.
• Provide positive routing: relevant historical questions use focused search; explicit inventory uses list; explicit save requests use remember; handoff and review use their available workflows. Ordinary coding should not trigger redundant calls merely because tools are exposed.
• State observable result meanings: accepted Source evidence is not necessarily produced Memory; a generated candidate is not an approved artifact; a failed operation must not be reported as saved or restored.
• Keep tool descriptions independently useful while putting detailed multi-step procedures in Skills. Preserve PowerContext's own citation, authorization, and human-review rules rather than copying Cordis-specific approval or autonomous-retry behavior.

PowerContext already registers GUIDANCE through systemPrompt.section; D should improve that existing mechanism. It can reference the currently shipped project-context Skill and therefore does not need to wait for E's naming/distribution changes.

Refinement to E

Keep feat(integrations): add layered PowerContext Skill routing, with explicit agreement between system guidance, the discoverable Skill catalog, and loaded Skill bodies:

• Point only to Skills actually available in the current host. Update references together with the agreed project-context migration and the naming/distribution work in Tracking Issue: deterministic Agent distributions from one canonical plugin #1405 / docs(rfc): define deterministic agent plugin distributions #1410.
• Put clear English/Chinese task intents early in the model-visible description. DSH's catalog renderer publishes name and description, with a configurable description limit (500 characters by default); whenToUse alone does not supply catalog routing.
• Keep the router small and load detailed Memory, Handoff, and Review procedures when applicable, without requiring a PowerContext Skill detour before every response.

Acceptance evidence

Inspect the actual model request/context browser for consistent system guidance, tool definitions, and visible Skill names; then evaluate task behavior with Skills available and unavailable. Cover ordinary coding, focused historical lookup, explicit inventory, explicit remembering, handoff, human review, and unavailable operations. Verify actual calls and honest result reporting. Longer descriptions or keyword counts are not acceptance criteria, and the screenshots/source alone do not establish improved model behavior.

This refines D/E within this tracker. B continues to own automatic-path diagnostics and presentation of real recalled content; F continues to own accumulated operational status. The original tracker body is retained for traceability.

AI assistance: OpenAI Codex assisted with source inspection and this alignment proposal.

[knqiufan]

Work package B is now tracked in #1457: bug(dsh): complete automatic-path diagnostics and recall presentation.

Implementation is being developed on #1452's commit c776cddf, reusing A's error classification and Scope cancellation support. The registered-entry regression baseline is 28 tests: 8 passing and 20 failing on A. The fix will include real-Server e2e, built-plugin/real-DSH runtime checks, and recorded real-model Web usage before B is considered delivered.

A is still open and its branch belongs to a fork. B's upstream PR will therefore explicitly identify the dependency and provide a B-only comparison, then remove inherited A changes after A merges. This comment records the agreed development sequence; the tracker body remains unchanged.

[knqiufan]

Follow-up for B (#1457 / #1459): the Windows CI failure has been diagnosed and fixed, with the independent Server defect recorded in #1463 and its small fix in #1464.

The failure was caused by Windows text-mode writes expanding LF bytes in a 32-byte cursor signing key. The first Server process started, but restart rejected the longer persisted key. This is reproducible with a fixed input, so rerunning the same tests would only risk hiding the defect.

The fix writes binary bytes, adds deterministic persistence/restart coverage to Windows CI, and prints Server logs directly on native-service failure. It is included in B at d2b3ee25. Both #1464 and #1459 now have 17/17 passing checks, including real Linux/macOS/Windows service lifecycle tests and SQLite/OceanBase acceptance.

The earlier “admin rights” note concerned GitHub rejecting a request to rerun an old job. It was not the cause of the CI failure or a requirement for passing tests. GitHub's documented rerun requirement is repository write permission. The fix triggered normal PR validation without changing permissions or relaxing tests.

B remains Draft while the live-model HTTP 401 acceptance gate and its A dependency are unresolved. This Server correction does not change the B scope or mark the remaining tracking work complete.