fix(start): diagnose auxiliary listener failures and malformed edits

devlog/_plan/260912_operations/020_listeners.md

@@ -11,3 +11,5 @@ MODIFY existing tests/server/ports.test.ts and tests/server/loopback-listener-in
 MODIFY directly relevant structure/runtime.md, structure/config.md, structure/ops/service-and-sidecars.md and public hub/loopback guidance; link the canonical contract from other mapped ownership docs only where applicable. Review all conditional activation rows on hosted CI. Source inspection is not runtime proof.
 
 Design OPS-LIST-01..04 accepted with amendments. NEW tests/cli/cli-start-auxiliary-bind.test.ts, registered in both test-layout files, uses isolated CLI subprocess to cover soft and hard-pinned startup: failure names auxiliary key/address, exit nonzero, no public repick/wait branch. Existing management rollback fixture occupies management first then selects distinct public/loopback ports. Warning helper runs on all three load return paths plus read-only diagnostics; controls cover absent and valid-disabled entries and malformed secret-shaped input without echoing raw values.
+
+Follow-up090 validates raw managementIngress against the existing shared strict managementIngressSchema; disappearance of the entire hub block is not evidence that the ingress itself was malformed.

devlog/_plan/260912_operations/050_pairing.md

@@ -4,10 +4,28 @@ Class C3; dependency roadmap. Reuse existing connected-client state and browser-
 
 MODIFY owning dashboard pending-auth component and bootstrap state: distinguish a reachable connected machine awaiting hub browser authentication from a stopped standalone proxy. Show configured hub identity/origin, explain that machine enrollment and browser session are separate, offer the current origin-specific existing pairing/authentication action. Preserve revoked/expired/unreachable states and their existing retry actions; do not suggest ocx start while the local runtime is reachable. Derive the next action from current origin + configured hub instead of a hardcoded localhost URL. No credentials appear in visible copy/URLs.
 
-MODIFY all gui/src/i18n locale dictionaries with meaningful labels. Extend existing pending-auth/dashboard tests for local origin, remote hub origin, pending, authenticated, expired/revoked and unavailable standalone; positive browser auth transitions into connected dashboard. Exact files: gui/src/App.tsx, api.ts, pages/dashboard-core-poll.ts, pages/use-dashboard-data.ts and pages/Dashboard.tsx consume a classified authentication/error state instead of a boolean. Existing connect-pairing.ts and connect-pairing-transport.ts own hub identity and origin-specific action. Define the error classification in api.ts at response ingress; consume in polling and Dashboard; reset on authenticated success and pairing completion. No persistence/serialization for this UI state. Keep cached data with stale labeling when auth fails; do not erase a known hub into standalone offline. Public hub/browser-pairing guidance is updated with the same distinction. No service restart or live auth reconfiguration.
+MODIFY all gui/src/i18n locale dictionaries with meaningful labels. Extend existing pending-auth/dashboard tests for local origin, remote hub origin, pending, authenticated, expired/revoked and unavailable standalone; positive browser auth transitions into connected dashboard. Exact files: gui/src/App.tsx, api.ts, pages/dashboard-core-poll.ts, pages/use-dashboard-data.ts and pages/Dashboard.tsx consume a classified authentication/error state instead of a boolean. Existing connect-pairing.tsx and connect-pairing-transport.ts own hub identity and origin-specific action. Define the error classification in api.ts at response ingress; consume in polling and Dashboard; reset on authenticated success and pairing completion. No persistence/serialization for this UI state. Keep cached data with stale labeling on non-auth read failures; hide it when authentication or permission is denied; do not erase a known hub into standalone offline. Public hub/browser-pairing guidance is updated with the same distinction. No service restart or live auth reconfiguration.
 
 Hosted component suite and screenshot artifact of the rendered pending state required for final delivery; local GUI tests/build NOT RUN. Static source or mockup is not rendered application evidence.
 
 Accepted OPS-PAIR-01/02. Cases include browser session expiry and post-pairing refresh, local and hub origin guidance, code versus API/admin-key explanation, and operator handoff text. Prefer existing component tests; new test files only where needed.
 
 Reflection amendments: reuse existing api.ts SESSION_UNAVAILABLE_EVENT and App sharedSessionReady; subscribe in App, emit on terminal 401 expiry (not aborted requests), reset/read refresh on successful pairing. Do not create duplicate auth state. Poll classification and pairing errors distinguish HTTP auth refusal, transport/network, and invalid responses; aborted work does not show a failure.
+
+P revalidation at81f0c78d7a: same App, Dashboard, pairing and API owners remain. This independent branch starts from refresheddev; previous usage-transportD directs pairing after the user-requested source repairs.
+
+Concrete delta: App subscribes to SESSION_UNAVAILABLE_EVENT for the shared plane and derives readiness from hasApiSession; ignore a late notice while a newer session is present. Pairing success increments a dashboard refresh epoch and marks ready. Pass connected/authenticationPending into Dashboard. Hide protected dashboard content while authentication is pending; keep known data with a stale notice only on non-auth read failures. In fetchDashboardOverview distinguish 401(auth), 403(denied), other non-OK(request), invalid JSON/shape(invalid), and transport failure(unavailable); aborted polls propagate without publishing an error. Hook exposes failure and overview refresh without a second authentication store. Only standalone transport unavailability may show ocx start; connected/auth/invalid/request failures use relevant copy and retry.
+
+API wrapper emits its existing unavailable event on terminal401 only when the caller is not aborted and no newer session exists. Retain credential refresh/singleflight behavior; no new auth bypass or token persistence. Dashboard receives success epoch as a prop; useDashboardData adds it to existing useKeyedClientResource revalidation dependencies without changing resource keys or remounting. Every dashboard resource refreshes even when a settled failed/cached store survived.
+
+Pairing form shows target.serverOrigin, a copyable ocx gui pair --origin command for window.location.origin, instructions to run it on the hub or ask its operator, and the distinction between one-time code and API/admin keys. Reuse useCopyFeedback and existing copy labels; copy failure remains visible. Keep relay technical copy subordinate. Pairing transport gets a typed error kind (invalid-code/refused/unreachable/invalid-response), mapped to localized actionable copy while preserving pasted code; abort does not publish an error. This is process-local UI state, not a wire schema.
+
+Exact regressions: extend gui/tests/connect-pairing.test.ts for real App dashboard pending/authsuccess/expiry/recovery and hub/command identity; extend api-auth-deadline.test.ts for terminal notice behavior if needed; NEW gui/tests/dashboard-connection-state.test.ts for poll failure classes, cached data and no erroneous start advice. All9 locale modules get new copy. Existing Notice/buttons/tokens, variance2/motion1, dense utility layout; no decorative assets or new dependencies. Hosted built preview, inspected screenshot and browser interaction supply rendered proof later; local suites/build NOT RUN.
+
+Pairing lifetime precision: form keyed by target server/bootstrap identity, one AbortController per submit cancelled on unmount; transport accepts optional caller signal in addition to its existing fetch seam and checks abort before session installation. This prevents an obsolete target response from installing a session or publishing errors after its form unmounts. Keep existing request method/credential mechanics unchanged.
+
+A amendment: post-pairing refresh explicitly reaches each dashboard keyed resource through [apiBase, refreshEpoch] dependencies; a component remount is not treated as a cache invalidation mechanism. Regression first seeds a failed overview store, completes pairing, and requires a new authenticated health/provider read plus rendered data.
+
+Reflection03/05 closure:403 keeps distinct permission-denied guidance and never starts or re-pairs a running proxy merely for denied permissions. Validate HealthData status/version strings and finite nonnegative uptime; providers must be an array of objects with the required name/adapter/baseUrl strings and hasApiKey boolean, optional defaultModel string. Invalid shapes are classified invalid even with HTTP200. Unauthorized/denied content stays hidden; only nonauth read failure may show cached data with stale notice.
+
+Resume C repairs: hosted34682559994 found erasableSyntaxOnly constructor parameter-property and React ref analysis at createElement form. Explicit class field and JSX component preserve behavior without disabling rules. Source compound-failure repair was already published externally at4124a644; local byte-identical patch preserved before fast-forward. Hidden-document App fixture disables periodic polls, and a controlled real resource deadline verifies retained data becomes stale. All local suites/build/typecheck/install NOT RUN.

devlog/_plan/260912_operations/060_transport.md

@@ -5,3 +5,5 @@ Class C4; dependency roadmap. Scope #4315 and the current CHANGES_REQUESTED revi
 The executable security design and negative-case audit live only in ignored .tmp/operations/060_transport_private.md. That file must be completed and independently reviewed before B; no pre-disclosure reasoning is copied into public planning history. Public deliverable is the implementation, regression tests and shipped contract text only. Required review dimensions: local destination selection, redirect and proxy-environment behavior, credential separation and all current callers. Original contributor credit: Cortes Ventures <admin@cortesventures.com>. No fallback that substitutes a data credential for admin authentication.
 
 Hosted regression execution plus independent security source audit bind the final patch SHA. Review state is refreshed before handoff; this work cannot approve or merge the original PR. Local suites/build/typecheck/install NOT RUN.
+
+P resume revalidation at c311f9bf7f5003af29fa8e7ebc2f2b5db20267f6: original4317 still CHANGES_REQUESTED, helper and sole productioncaller unchanged. Prior pairingD directs this independent slice. Reuse direct-local-http transport and local-destinations resolver; private060 contains exact diff contract and controls. No new dependencies, service changes or fallback settings. Existing8s deadline retained. New tests/providers/opencode-management-transport.test.ts isolates real socket/proxy/redirect controls and registers in both test-layout maps. Existing opencode-cli caller test changes transport spy and checks distinct management/inference credentials and generated blocks.

devlog/_plan/260912_operations/070_verification.md

@@ -7,3 +7,9 @@ For each independently mergeable branch: record git rev-parse HEAD, original sou
 A local receipt may run git diff --check and read-only hosted-result assertions; it is not a local test result. Local suites, typecheck/build/install are NOT RUN. Final behavior acceptance comes from GitHub-hosted test runs at the final SHA and independent review; author reports/old green CI are not substituted.
 
 Update ignored .tmp/operations/handoff.md as soon as each artifact exists. Include outstanding issue acceptance, original author trailers, unresolved maintainer objections, exact run links/conclusions and cycle ledger pointers. Publish template-complete PR bodies with truthful verification, screenshots for changed dashboard UI and no private investigation notes. Parent owns all integration decisions.
+
+P resume amendment: reconcile at pinned origin/dev db7062c37a84b12c4f59abc567d07241bf2a6042, which includes separately owned Cline/native-restore fixture repairs. No repeated rewrites. Fast-forward local lane refs to parent-published remote heads before edits; merge the pinned baseline into owned feature branches only where needed to incorporate failed-check repairs/conflicts. Never move dev/main/preview or merge PRs. Preserve shared changes and resolve only operations-owned conflicts; record any cross-lane source collision for parent.
+
+Listener4353 also has a documentation-only review requiring the plan to describe reuse of the already-existing managementIngressSchema. Correct020/090 wording, do not duplicate a schema. Totals4357 consumes baseline then child4373 receives that exact lower head; verify ancestry and original source patch parity. Pairing4378 incorporates baseline only once and retains all source repairs. Transport4402 is already based on repaireddev; do not rewrite its unchanged candidate for unrelated later commits.
+
+Final requested gate is hosted laneall on listener, cumulative usage child, pairing, and transport. Inspect live job outcomes and exacthead. New failures inside this lane become separately audited repaircycles; external owner failures are recorded without duplicate edits or baselinegreen claims. Read build artifacts from hosted GUI jobs, serve only those static files with fixture responses in isolated scratch for screenshot/interaction review, no product build/test/server locally. This is render observation, not a local suite. No liveuser service/config changes.

devlog/_plan/260912_operations/090_listener_diagnostic.md

@@ -0,0 +1,7 @@
+# Precise ingress degradation diagnosis
+
+User intake4353 discussion3995160105. P amendment reprioritizes a source review repair before pairing; pairing source was not changed. Class C2, satisfy-spec, same tool/write bounds and no resource cap; no local suite/build/typecheck/install, no merges/services. Final behavior proof is hosted CI.
+
+Valid managementIngress is currently blamed when an invalid sibling makes the whole hub parse disappear. MODIFY src/config.ts: reuse the existing private managementIngressSchema in hubConfigSchema and raw-field validation; test the raw ingress with that same strict schema before issuing its field-specific warning. Do not change normalization, acceptance, port relationship validation, or whole-hub warnings. Rawvalues never printed.
+
+MODIFY tests/config/config-load-degrade.test.ts: valid ingress plus invalid dataPublicOrigin must warn about the actual hub sibling and not claim managementIngress invalid; preserve file bytes. Existing malformed-ingress cases still warn. Update020 and structure/config.md canonical wording. Independent source re-audit then authorized comment reply/resolution; hosted criterion remainsOPEN.

devlog/_plan/260912_operations/110_resume_status.md

@@ -0,0 +1,9 @@
+# Operations resume checkpoint
+
+Update carry #4343 merged with exact candidate f37894711158fa8215d26bed642389148ac395f6 and successful Cross-platform CI34674523305. The already-carried stop fix is not replayed. Original issue/PR closure stays with integration coordination.
+
+Listener #4353, usage #4357 → #4373 and pairing #4378 remain open. Published usage source/security audits passed; hosted execution must be checked on the final cumulative tip. Prior Cline registration/native-restore fixture failures are retained as failures; current dev has a separate repair, and this unit does not duplicate its ownership.
+
+Pairing resumed at persisted C. The previous local compound-failure patch matched the newer remote commit byte-for-byte and was preserved before fast-forward. The subsequent fix uses an erasable explicit error field and JSX event handlers for the hosted compiler/lint failures; no checks were disabled. A hidden-document pairing fixture excludes periodic polling, and a controlled resource deadline verifies stale-data marking. Hosted execution and rendered preview remain pending.
+
+The OpenCode management-token and local transport change remains outstanding against original #4317 CHANGES_REQUESTED. No whole-lane completion is claimed. All local suites, focused tests, GUI tests, build, typecheck and installs are NOT RUN. No service changes or release actions were performed.

devlog/_plan/260912_operations/120_coordinator_probe.md

@@ -0,0 +1,15 @@
+# Coordinator-refusal fixture diagnostics
+
+The Windows5 failure in run34693005384 ended the transaction child at its existing15-second deadline before result assertions. The failed head and current dev have identical scoped test/connect/lock/ACL source. The log does not identify the stalled phase, so this work adds evidence and strengthens the coordinator-specific oracle; it does not claim to repair a proven production stall.
+
+Class C2, satisfy-spec, triggered by parent triage assignment. Scope: tests/clients/client-connect.test.ts and this plan only. No runtime, ACL policy, unrelated fixture, or timeout-budget changes. Local suites/build/typecheck/install NOT RUN; manual hosted dispatch/rerun HOLD. Existing publication and independent model-inheriting source review remain authorized. Stop this diagnostic slice when source reviewed and published; actual Windows outcome remains open until authorized hosted execution. Original operations verification criteria remain unchanged/open in verification-resume after the cancelled-CI checkpoint.
+
+MODIFY the existing transaction child script: synchronously emit fixed JSON phase markers on stderr around module load, connect invocation/completion, state observation and result publication. Markers contain only an allowlisted phase and bounded nonnegative integer elapsed milliseconds. They contain no home paths, URL, credentials, error text or raw output.
+
+MODIFY the parent fixture: parse only those marker objects on failure before throwing ClientStateProbeError, and include only validated phase/elapsed evidence. Preserve15-second kill, successful exit requirement, output parse and all cleanup. A valid result followed by a retained child still fails. Unknown/malformed marker fields are ignored; never expose raw stderr/stdout. Existing other fixtures keep the same constructor behavior.
+
+MODIFY the coordinator oracle: inspect the caught cause chain for the exact CONFIG_MUTATION_LOCK_UNAVAILABLE code and expose only a boolean in fixture JSON. Assert this in addition to connected=null, calls=[], absent token/catalog and zeroed authority. An earlier lifecycle refusal must not pass as coordinator coverage. No matching on arbitrary raw error prose.
+
+Extend existing fixture self-checks with valid phase evidence on a retained child and malformed/unknown/secret-shaped marker controls. All original expectations remain. Independent A/C review checks marker privacy, actual reachability, timeout/cleanup retention and unchanged production source. git diff --check is whitespace evidence only. Hosted execution after HOLD must distinguish module loading, connect-internal delay and completed-result exit retention; until then no root-cause or baseline-green claim.
+
+Design reflection accepted: cause traversal uses a seen-object set and finite depth; connect markers distinguish entered, resolved and rejected outcomes; result_published follows serialization/output. Parent scans a bounded stderr tail and accepts only fixed phase names plus finite nonnegative integer elapsed milliseconds within a fixed cap. A valid marker followed by malformed input retains the valid evidence. These markers do not identify a particular inner ACL/lock call.

docs-site/src/content/docs/guides/opencode.md

@@ -201,3 +201,5 @@ opencode must be installed and on `PATH`:
 ```bash
 npm install -g opencode-ai
 ```
+
+The launcher reads the model catalog with the local admin token from the environment or the running proxy home. It connects directly to a loopback management listener and refuses redirects. A hub bound only to a nonlocal address needs its loopback `hub.managementIngress` enabled. The admin token is not passed into the OpenCode child; inference continues using its separate data key. If the local admin token is missing, the launcher reports the problem rather than retrying with a data key.