> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session07-connection-probe-parity/spec.md).

# Session Specification

**Session ID**: `phase40-session07-connection-probe-parity` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: b871f8890d43d8cd0626eb894b760c590a6219d6

***

## 1. Session Overview

This session ports the useful upstream Hermes connection-probe behavior into AI OS without moving bridge logic back into Vite middleware. The current AI OS `/__hermes_connections` endpoint already reports configured providers, `auth.json` providers, gateway tokens, generic service env keys, and memory availability. This session adds the missing safe CLI-backed service probes, status-only caching, and explicit non-TTY MCP skip rationale.

The work is next because Sessions 01-02 recorded the Phase 40 port invariants and provider readiness helpers, while Sessions 03-06 hardened shared redaction and bridge write patterns. Connection probing is a read-only bridge expansion, but it still touches local tools and auth state, so it must preserve the Phase 40 local-control-plane and no-raw-private-output constraints.

The session delivers backend probe parity and the browser-safe response/UI contract needed before later catalog, model-intelligence, and Ministry sessions build on connection status. It does not add shell snippets, raw command output, or TTY-unsafe Hermes MCP execution.

***

## 2. Objectives

1. Add allowlisted, non-shell, no-output CLI probes for GitHub, Google Workspace, Linear, and Spotify to `GET /__hermes_connections`.
2. Preserve existing provider, gateway, generic env-service, and memory connection summaries while adding a 30 second status-only cache.
3. Expose an explicit browser-safe MCP probe skip rationale without running `hermes mcp list`.
4. Add focused bridge, parser, hook, and component tests for connected, missing, timeout, cache, skip-rationale, and no-leak behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session01-baseline-and-port-invariants` - Provides the semantic port invariants, owner mapping, and no-wholesale-copy rule.
* [x] `phase40-session02-models-and-provider-readiness` - Provides provider alias, env-key, and readiness helpers used by the current connection endpoint.
* [x] `phase40-session03-shared-redaction-foundation` - Provides shared browser-visible sanitizer behavior for bridge output.
* [x] `phase40-session06-moa-save-endpoint` - Confirms the current Phase 40 bridge/test/state handoff is complete and `current_session` is clear.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Existing Hermes read bridge owner in `scripts/lib/hermes-dev-bridge.ts`.
* Existing CLI resolution helper in `scripts/lib/tool-detection.ts`.
* Existing connection parser and UI owner in `src/lib/hermes-types.ts` and `src/components/hermes/hermes-connections.tsx`.

### Environment Requirements

* Local checkout with dependencies installed or installable through `bun install`.
* No live GitHub, Google Workspace, Linear, Spotify, Notion, Airtable, Hermes MCP, or provider credentials required; tests must use injected probe outcomes, temp Hermes homes, synthetic env files, and mocked bridge requests.

***

## 4. Scope

### In Scope (MVP)

* AI OS exposes CLI-backed service coverage for GitHub, Google Workspace, Linear, and Spotify through `GET /__hermes_connections`.
* CLI probes use allowlisted argv arrays only: `gh auth status`, `gws auth status`, `linear whoami`, and `spotify auth status`.
* CLI probes are non-shell, timeout-bounded, no-output, and return status only.
* Probe status is cached for 30 seconds without storing command stdout, stderr, env values, account IDs, emails, private paths, or tokens.
* Existing provider readiness, `auth.json`, gateway token, generic env-service, and memory rows continue to work.
* Notion and Airtable remain env-parsed token-only service checks through existing generic env-key scanning.
* `hermes mcp list` remains intentionally skipped until Hermes exposes a safe non-interactive command.
* The browser contract includes an explicit, sanitized skipped-probe rationale.
* The Hermes connections UI renders the skipped-probe rationale as product copy and does not expose diagnostics or command output.

### Out Of Scope (Deferred)

* Running `hermes mcp list` - Reason: the folded Phase 40 source records it as TTY-unsafe and potentially hanging.
* Broad shell snippets or user-configurable probe commands - Reason: probe execution must stay allowlisted, non-shell, and bounded.
* Surfacing command output, env values, account IDs, emails, paths, or tokens - Reason: connection responses are browser-visible local bridge reads.
* Adding new third-party auth flows - Reason: this session only detects existing local CLI/env readiness.
* Changing provider model catalog behavior - Reason: Session 08 owns catalog and context metadata.

***

## 5. Technical Approach

### Architecture

Add a small read-only probe helper under `scripts/lib/` and integrate it from `readHermesConnections()` in `scripts/lib/hermes-dev-bridge.ts`. The helper owns the allowlisted probe definitions, CLI path resolution, timeout-bounded spawn behavior, no-output stdio configuration, and status-only cache. The bridge continues to own response composition, existing Hermes file/env reads, duplicate connection suppression, sorting, and final browser-safe projection.

Extend the shared browser type/parser in `src/lib/hermes-types.ts` with a skipped-probe summary list rather than overloading connection statuses. Update `src/components/hermes/hermes-connections.tsx` to render that rationale in the existing connection panel without adding a debug surface. Existing `useHermes()` fetch behavior should continue to parse the expanded body.

### Design Patterns

* Split bridge owner: Keeps local read behavior in `scripts/lib/` rather than adding monolithic Vite middleware logic.
* Allowlisted argv definitions: Prevents shell expansion, arbitrary commands, and accidental broad local probing.
* Status-only cache: Avoids repeated CLI process cost while preventing secret or account material from entering memory.
* Parser-owned browser contract: Keeps expanded response shape validation out of UI components.

***

## 6. Deliverables

### Files To Create

| File                                                     | Purpose                                                                                                      | Est. Lines |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------- |
| `scripts/lib/hermes-connection-probes.ts`                | Allowlisted no-output CLI probe definitions, timeout runner, and 30 second status-only cache.                | \~190      |
| `scripts/lib/__tests__/hermes-connection-probes.test.ts` | Unit tests for probe success, missing CLI, timeout, cache TTL, no-output behavior, and allowlist boundaries. | \~220      |

### Files To Modify

| File                                                       | Changes                                                                                                                                         | Est. Lines |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-dev-bridge.ts`                         | Integrate cached CLI probes into `readHermesConnections()`, add skipped MCP rationale to response, and keep existing connection sources intact. | \~80       |
| `scripts/lib/__tests__/hermes-dev-bridge.test.ts`          | Add endpoint-level tests for CLI probe rows, skip rationale, timeout/missing behavior, cache reuse, and no private output leakage.              | \~180      |
| `src/lib/hermes-types.ts`                                  | Add skipped connection probe types and parser validation for expanded `HermesConnectionsBody`.                                                  | \~50       |
| `src/lib/__tests__/hermes-types.test.ts`                   | Add parser coverage for skipped probe summaries and malformed skip payloads.                                                                    | \~45       |
| `src/hooks/__tests__/use-hermes.test.tsx`                  | Update connection fixtures and hook error coverage for expanded connection bodies.                                                              | \~35       |
| `src/components/hermes/hermes-connections.tsx`             | Render skipped MCP rationale as product-facing connection context without exposing diagnostics.                                                 | \~70       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Add component coverage for rendered skip rationale and existing filters.                                                                        | \~50       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `GET /__hermes_connections` includes GitHub, Google Workspace, Linear, and Spotify CLI-backed service rows when their allowlisted probes succeed.
* [ ] Missing CLIs, non-zero exits, and timeouts do not fail the endpoint and do not expose command output.
* [ ] Notion and Airtable token-only service detection remains env-parsed.
* [ ] The response explicitly reports that Hermes MCP probing is skipped because `hermes mcp list` is TTY-unsafe.
* [ ] Probe status is reused within 30 seconds and refreshed after the TTL.

### Testing Requirements

* [ ] Unit tests written and passing for the probe helper.
* [ ] Endpoint tests written and passing for connected, missing, timeout, cache, skip, and no-leak behavior.
* [ ] Parser, hook, and component tests updated for the expanded connection response.

### Non-Functional Requirements

* [ ] No connection response contains stdout, stderr, env values, raw private paths, emails, account IDs, auth JSON, tokens, or token-shaped strings.
* [ ] CLI execution uses non-shell process spawning with explicit argv arrays, ignored stdio, timeout cleanup, and no broad command input.
* [ ] The UI keeps diagnostics out of product-facing connection cards.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] User-facing surfaces contain product-facing copy only

***

## 8. Implementation Notes

### Working Assumptions

* The session should implement connection probe parity in the current split Hermes bridge, not in Vite middleware: Phase 40 requires semantic ports into existing AI OS owners, and the shipped `GET /__hermes_connections` route is owned by `scripts/lib/hermes-dev-bridge.ts`.

### Conflict Resolutions

* The folded Phase 40 source lists Notion and Airtable among upstream service checks, while the session stub says to prefer env parsing for token-only checks. The chosen interpretation is to keep Notion and Airtable in generic env-key scanning and add CLI execution only for GitHub, Google Workspace, Linear, and Spotify because those are the explicitly allowlisted argv probes.

### Key Considerations

* Preserve AI OS naming and local operator boundaries; this is Hermes local bridge behavior, not Trend Finder source collection.
* Do not introduce new global `findtrend` identifiers.
* The project has no database layer, so no schema migration or DB verification tasks apply.

### Potential Challenges

* CLI availability differs per machine: tests should inject probe outcomes and not require installed external CLIs.
* Cache state can make tests order-sensitive: expose a narrow reset or dependency-injection seam in the helper test surface only.
* Output leakage can happen through process errors: ignore stdio and normalize every failed probe to status-only metadata.

### Relevant Considerations

* \[P38] **Local control-plane gates are defense in depth**: Preserve loopback, Host-header, token, method, timeout, and safe-error behavior for local bridge reads.
* \[P38] **Upstream ports are semantic, not wholesale**: Map upstream behavior into existing AI OS module owners instead of copying upstream files.
* \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: CLI/env/auth status must remain browser-safe and redacted.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* External CLI probes hanging or producing private output.
* Browser-visible connection payloads leaking local auth/account details.
* Cache behavior hiding updated readiness or persisting sensitive material.

***

## 9. Testing Strategy

### Unit Tests

* Test `scripts/lib/hermes-connection-probes.ts` with fake resolver, fake process runner, controlled clock, and injected allowlisted probe definitions.
* Verify success, missing command, non-zero exit, timeout, cache hit, cache expiry, ignored output, and allowlist shape.

### Integration Tests

* Extend `scripts/lib/__tests__/hermes-dev-bridge.test.ts` to call `GET /__hermes_connections` with temp Hermes homes and injected probe outcomes.
* Extend `src/lib/__tests__/hermes-types.test.ts`, `src/hooks/__tests__/use-hermes.test.tsx`, and `src/components/hermes/__tests__/hermes-sections.test.tsx` for the expanded body and UI context.

### Runtime Verification

* Run the focused suite: `bunx vitest run scripts/lib/__tests__/hermes-connection-probes.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`.
* Run `bun run typecheck:scripts`, `bun run typecheck`, and `git diff --check`.

### Edge Cases

* CLI binary missing, inaccessible, non-zero, slow, or throws on spawn.
* Probe succeeds with stdout/stderr containing emails, account IDs, paths, or token-shaped strings; output must still be ignored.
* Duplicate service rows from env scanning and CLI probing.
* Cache hit after Hermes home/env changes within TTL; acceptable because cache stores status only and expires after 30 seconds.
* Malformed expanded connection responses from stale demos or tests.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session01-baseline-and-port-invariants`, `phase40-session02-models-and-provider-readiness`, `phase40-session03-shared-redaction-foundation`, `phase40-session06-moa-save-endpoint`
* Depended by: `phase40-session08-catalog-and-context-metadata`, `phase40-session09-model-intelligence-and-pricing`, `phase40-session18-full-validation-and-handoff`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session07-connection-probe-parity/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.