> 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/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase40-session07-connection-probe-parity` **Started**: 2026-07-03 02:47 **Last Updated**: 2026-07-03 03:09

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 20 / 20 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Implementation Summary

* Added allowlisted GitHub, Google Workspace, Linear, and Spotify CLI probes with fixed argv arrays.
* Added non-shell, ignored-stdio, timeout-bounded probe execution with status-only missing, error, non-zero, timeout, and success results.
* Added a 30 second status-only cache keyed by probe ID and command availability.
* Integrated CLI probe rows into `GET /__hermes_connections` without replacing existing provider, auth.json, gateway, generic env-service, Notion, Airtable, or memory rows.
* Added a browser-safe skipped Hermes MCP probe summary while continuing to avoid `hermes mcp list` execution.
* Extended the browser parser, hook fixtures, demo fixture, and connection panel to support skipped-probe summaries.
* Added focused helper, bridge, parser, hook, and component coverage for connected, missing, timeout, cache, duplicate suppression, skip-rationale, and no-leak behavior.

## Validation Summary

* Focused connection suite: PASS - 5 files, 140 tests.
* Script and app typechecks: PASS - `bun run typecheck:scripts && bun run typecheck`.
* Lint: PASS - `bun run lint` after formatting touched files.
* Whitespace/encoding: PASS - `git diff --check`, changed-file ASCII scan, and CRLF scan.
* Remaining blockers: none.

***

### Task T020 - Update implementation notes with shipped coverage and validation evidence

**Started**: 2026-07-03 03:08 **Completed**: 2026-07-03 03:09 **Duration**: 1 minute

**Notes**:

* Added the final implementation summary for shipped probe coverage, cache behavior, MCP skip rationale, parser/hook/UI changes, and validation evidence.
* Updated session progress to 20 / 20 tasks with no remaining blockers.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Added final implementation and validation summary.

**Verification**:

* Command/check: `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`
  * Result: PASS - focused connection probe suite passed.
  * Evidence: Vitest reported 5 test files passed and 140 tests passed.
* Command/check: `bun run typecheck:scripts && bun run typecheck`
  * Result: PASS - script and app TypeScript projects passed.
  * Evidence: Final run completed `tsc --noEmit -p tsconfig.scripts.json` and `tsc --noEmit` with exit code 0.
* Command/check: `bun run lint`
  * Result: PASS - lint passed after Prettier formatting.
  * Evidence: Final run completed `eslint .` with exit code 0.
* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors detected.
  * Evidence: Command exited 0 with no output.
* UI product-surface check: PASS - implementation notes record component coverage proving skipped MCP context renders as product copy without raw command details.
* UI craft check: PASS - implementation notes record component coverage proving filter behavior remains stable with the skipped-probe note.

***

### Task T019 - Validate ASCII, LF, and diff whitespace

**Started**: 2026-07-03 03:07 **Completed**: 2026-07-03 03:08 **Duration**: 1 minute

**Notes**:

* Ran diff whitespace validation.
* Ran changed-file ASCII and CRLF checks to cover the session encoding requirements.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T019 validation evidence.

**Verification**:

* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors detected.
  * Evidence: Command exited 0 with no output.
* Command/check: `status=0; while IFS= read -r file; do [ -f "$file" ] || continue; if ! LC_ALL=C perl -ne 'if (/[^\\x00-\\x7F]/) { print "$ARGV:$.: non-ascii\\n"; exit 1 }' "$file"; then status=1; fi; if LC_ALL=C grep -n $'\\r' "$file" >/tmp/aios-crlf-check.$$ 2>/dev/null; then sed "s#^#$file:#" /tmp/aios-crlf-check.$$; status=1; fi; rm -f /tmp/aios-crlf-check.$$; done < <(git diff --name-only --diff-filter=ACM); exit "$status"`
  * Result: PASS - changed files contain ASCII-only text and no CRLF line endings.
  * Evidence: Command exited 0 with no output.
* UI product-surface check: N/A - encoding/whitespace validation only.
* UI craft check: N/A - encoding/whitespace validation only.

***

### Task T018 - Run lint for touched linted code paths

**Started**: 2026-07-03 03:06 **Completed**: 2026-07-03 03:07 **Duration**: 1 minute

**Notes**:

* Ran lint for the touched script, source, hook, and component paths.
* Initial lint run found Prettier formatting issues in the new probe helper/test and the updated bridge test.
* Ran Prettier on touched source/test files, then reran lint successfully.

**Files Changed**:

* `scripts/lib/hermes-connection-probes.ts` - Prettier formatting.
* `scripts/lib/__tests__/hermes-connection-probes.test.ts` - Prettier formatting.
* `scripts/lib/__tests__/hermes-dev-bridge.test.ts` - Prettier formatting.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T018 lint evidence.

**Verification**:

* Command/check: `bun run lint`
  * Result: PASS - ESLint/Prettier lint passed after formatting.
  * Evidence: Final command completed `eslint .` with exit code 0.
* Command/check: `bunx prettier --write scripts/lib/hermes-connection-probes.ts scripts/lib/__tests__/hermes-connection-probes.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/hermes-types.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx src/components/hermes/hermes-connections.tsx src/components/hermes/__tests__/hermes-sections.test.tsx src/lib/hermes-demo-data.ts`
  * Result: PASS - formatting applied to the files that lint identified.
  * Evidence: Prettier reported changes to the probe helper/test and bridge test, with other touched files unchanged.
* UI product-surface check: N/A - lint/format only.
* UI craft check: N/A - lint/format only.

**BQC Fixes**:

* Contract alignment: Formatting brought the changed TypeScript files back under the repository lint contract.

***

### Task T017 - Run script and app typechecks

**Started**: 2026-07-03 03:05 **Completed**: 2026-07-03 03:06 **Duration**: 1 minute

**Notes**:

* Ran script and app typechecks for the bridge, helper, parser, hook, fixture, and component shape changes.
* The first app typecheck caught `HERMES_DEMO_CONNECTIONS` missing the required `skippedProbes` field.
* Updated the demo-safe connection fixture with a skipped Hermes MCP summary, then reran both typechecks successfully.

**Files Changed**:

* `src/lib/hermes-demo-data.ts` - Added demo-safe `skippedProbes` fixture data to `HERMES_DEMO_CONNECTIONS`.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T017 typecheck evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts && bun run typecheck`
  * Result: PASS - script and app TypeScript projects passed after fixture alignment.
  * Evidence: Final run completed `tsc --noEmit -p tsconfig.scripts.json` and `tsc --noEmit` with exit code 0.
* UI product-surface check: N/A - typecheck only.
* UI craft check: N/A - typecheck only.

**BQC Fixes**:

* Contract alignment: Typecheck caught and the session fixed the demo connection fixture to match the expanded `HermesConnectionsBody` contract (`src/lib/hermes-demo-data.ts`).

***

### Task T016 - Run focused connection probe suite

**Started**: 2026-07-03 03:04 **Completed**: 2026-07-03 03:05 **Duration**: 1 minute

**Notes**:

* Ran the required focused suite covering the probe helper, bridge endpoint, browser parser, hook, and component surfaces.
* Confirmed all new and updated focused tests pass together.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T016 validation evidence.

**Verification**:

* Command/check: `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`
  * Result: PASS - focused connection probe suite passed.
  * Evidence: Vitest reported 5 test files passed and 140 tests passed.
* UI product-surface check: PASS - included component coverage verifies skipped-probe product copy and no raw command details.
* UI craft check: PASS - included component coverage verifies connection filter behavior remains stable with the new skip note.

***

### Task T015 - Add component tests for skipped probe rendering

**Started**: 2026-07-03 03:03 **Completed**: 2026-07-03 03:04 **Duration**: 1 minute

**Notes**:

* Updated the Hermes connection component fixture to include the expanded `skippedProbes` response field.
* Added assertions that the Hermes MCP skip note renders as product copy.
* Added assertions that raw response details such as `hermes mcp list` and `TTY-unsafe` are not rendered in the normal product surface.
* Confirmed existing connection filter behavior still works and the skip note remains visible while filtering rows.

**Files Changed**:

* `src/components/hermes/__tests__/hermes-sections.test.tsx` - Added skipped-probe fixture data and UI assertions.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T015 evidence.

**Verification**:

* Command/check: `bunx vitest run src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - Hermes component tests passed with skipped-probe assertions.
  * Evidence: Vitest reported 1 test file passed and 89 tests passed.
* UI product-surface check: PASS - test verifies product copy renders and raw command details are absent from visible text.
* UI craft check: PASS - test verifies the skip note remains stable while the row filter changes visible connection cards.

**BQC Fixes**:

* Product surface discipline: Component tests now guard against raw MCP command details appearing in the visible connection panel (`src/components/hermes/__tests__/hermes-sections.test.tsx`).
* Contract alignment: Component fixture now matches the expanded `HermesConnectionsBody` contract (`src/components/hermes/__tests__/hermes-sections.test.tsx`).

***

### Task T014 - Render skipped MCP rationale in the connection panel

**Started**: 2026-07-03 03:02 **Completed**: 2026-07-03 03:03 **Duration**: 1 minute

**Notes**:

* Added skipped-probe normalization in the Hermes connection panel.
* Rendered Hermes MCP skip context as product-facing copy that explains browser-read safety without echoing raw command strings or diagnostics.
* Kept the existing connection stats, filters, and row layout intact.

**Files Changed**:

* `src/components/hermes/hermes-connections.tsx` - Added skipped-probe context rendering with normalized product copy.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T014 evidence.

**Verification**:

* Command/check: `bunx vitest run src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - existing Hermes component tests still pass after the connection panel change.
  * Evidence: Vitest reported 1 test file passed and 89 tests passed.
* UI product-surface check: PASS - component renders product copy for skipped probes and does not render raw skip reason text from the response.
* UI craft check: PASS - added the skipped-probe note as a compact bordered row inside the existing connection panel rhythm, preserving dense stats and connection cards.

**BQC Fixes**:

* Product surface discipline: The UI maps skipped-probe IDs to product copy instead of exposing command strings or implementation diagnostics (`src/components/hermes/hermes-connections.tsx`).
* Contract alignment: The component tolerates absent or populated `skippedProbes` through parser-aligned defaults (`src/components/hermes/hermes-connections.tsx`).

***

### Task T013 - Update `useHermes` expanded connection fixtures

**Started**: 2026-07-03 03:01 **Completed**: 2026-07-03 03:02 **Duration**: 1 minute

**Notes**:

* Updated the hook connection fixture to include `skippedProbes`.
* Added a hook assertion that expanded connection data reaches the `connections` query view.
* Updated empty connection payload coverage to include an explicit empty skipped-probe list.
* Updated malformed connection payload coverage to verify skipped-probe parser errors map to the query error state.

**Files Changed**:

* `src/hooks/__tests__/use-hermes.test.tsx` - Updated connection fixtures and hook error coverage for expanded connection bodies.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T013 evidence.

**Verification**:

* Command/check: `bunx vitest run src/hooks/__tests__/use-hermes.test.tsx`
  * Result: PASS - hook tests passed with the expanded connection body.
  * Evidence: Vitest reported 1 test file passed and 12 tests passed.
* UI product-surface check: N/A - hook fixtures only.
* UI craft check: N/A - hook fixtures only.

**BQC Fixes**:

* Contract alignment: Hook tests now consume the expanded parser output and cover malformed skipped-probe bodies (`src/hooks/__tests__/use-hermes.test.tsx`).

***

### Task T012 - Add endpoint tests for probe parity and no-leak behavior

**Started**: 2026-07-03 03:00 **Completed**: 2026-07-03 03:01 **Duration**: 1 minute

**Notes**:

* Added deterministic endpoint tests with injected probe definitions, resolver outcomes, process outcomes, and controlled time.
* Covered connected GitHub, Google Workspace, Linear, and Spotify service rows.
* Covered missing and timeout probes returning `needs_setup` without leaking fake stdout, stderr, account, path, or token-shaped strings.
* Covered duplicate suppression when an env service already provides a GitHub row, while preserving Notion and Airtable token-only env parsing.
* Covered skipped Hermes MCP rationale and endpoint-level cache reuse within the TTL.
* Updated the bridge test harness to disable real CLI probes by default and clear probe cache around each test.

**Files Changed**:

* `scripts/lib/__tests__/hermes-dev-bridge.test.ts` - Added endpoint tests for CLI probes, missing/timeout statuses, dedupe, Notion/Airtable parsing, MCP skip rationale, cache reuse, and no-leak behavior.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T012 evidence.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-dev-bridge.test.ts`
  * Result: PASS - expanded bridge endpoint tests passed.
  * Evidence: Vitest reported 1 test file passed and 25 tests passed.
* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the updated endpoint tests.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* UI product-surface check: N/A - backend endpoint tests only.
* UI craft check: N/A - backend endpoint tests only.

**BQC Fixes**:

* State freshness on re-entry: Endpoint test coverage proves cached probe status is reused only within the TTL (`scripts/lib/__tests__/hermes-dev-bridge.test.ts`).
* Error information boundaries: Endpoint tests prove fake CLI output, private paths, account emails, auth filenames, and env values are absent from browser-visible responses (`scripts/lib/__tests__/hermes-dev-bridge.test.ts`).
* Contract alignment: Endpoint tests prove skipped MCP metadata and CLI service rows are present in the expanded connection body (`scripts/lib/__tests__/hermes-dev-bridge.test.ts`).

***

### Task T011 - Add browser-safe skipped MCP probe rationale

**Started**: 2026-07-03 02:59 **Completed**: 2026-07-03 03:00 **Duration**: 1 minute

**Notes**:

* Added a `skippedProbes` response list with a sanitized Hermes MCP skip summary.
* Recorded the rationale that Hermes MCP probing is skipped because `hermes mcp list` is TTY-unsafe for browser-triggered reads.
* Confirmed no code path executes Hermes MCP commands; the skipped summary is static response metadata.

**Files Changed**:

* `scripts/lib/hermes-dev-bridge.ts` - Added skipped-probe response type, static Hermes MCP skip summary, and `skippedProbes` in the connection response body.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T011 evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the expanded response type.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-dev-bridge.test.ts`
  * Result: PASS - existing bridge tests still pass with the expanded connection response.
  * Evidence: Vitest reported 1 test file passed and 21 tests passed.
* Command/check: `rg -n "hermes mcp|mcp list|spawn\\(" scripts/lib/hermes-dev-bridge.ts scripts/lib/hermes-connection-probes.ts`
  * Result: PASS - bridge contains only static MCP skip copy; process spawning remains isolated to allowlisted service probes.
  * Evidence: `hermes-dev-bridge.ts` contains the skip rationale string and no MCP execution; `hermes-connection-probes.ts` contains the only new `spawn()` call for allowlisted probe definitions.
* UI product-surface check: N/A - backend response metadata only; visible UI copy is handled by T014/T015.
* UI craft check: N/A - backend response metadata only.

**BQC Fixes**:

* External dependency resilience: TTY-unsafe MCP probing is represented as a skipped summary instead of executing an unbounded interactive command (`scripts/lib/hermes-dev-bridge.ts`).
* Error information boundaries: The skip summary is static sanitized text and contains no command output, paths, accounts, tokens, or env values (`scripts/lib/hermes-dev-bridge.ts`).

***

### Task T010 - Integrate cached CLI probes into connection reads

**Started**: 2026-07-03 02:57 **Completed**: 2026-07-03 02:59 **Duration**: 2 minutes

**Notes**:

* Integrated `runHermesConnectionProbes()` into `readHermesConnections()`.
* Added probe rows as `service` connections through the existing `kind:slug` duplicate suppression path.
* Preserved provider, auth.json, gateway token, generic env-service, and memory row behavior by leaving existing composition intact and adding CLI probes after generic env-service rows.
* Added bridge-level probe injection for tests so endpoint coverage can use fake resolver/runner outcomes without live CLIs.

**Files Changed**:

* `scripts/lib/hermes-dev-bridge.ts` - Added probe options to bridge options and integrated cached CLI probe results into connection rows.
* `scripts/lib/hermes-connection-probes.ts` - Added resolver-error mapping to keep injected resolver failures status-only.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T010 evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts bridge/helper integration.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-dev-bridge.test.ts`
  * Result: PASS - existing bridge behavior still passes after connection probe integration.
  * Evidence: Vitest reported 1 test file passed and 21 tests passed.
* Command/check: `sed -n '1660,1800p' scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - integration inspection confirms probe rows use `pushUniqueConnection()` and do not bypass existing connection sanitization/dedupe.
  * Evidence: CLI results are converted to `kind: "service"`, sanitized `name`, sanitized `slug`, and status-only `status`.
* UI product-surface check: N/A - backend bridge integration only.
* UI craft check: N/A - backend bridge integration only.

**BQC Fixes**:

* Failure path completeness: Resolver failures now map to status-only probe errors instead of failing the endpoint (`scripts/lib/hermes-connection-probes.ts`).
* Contract alignment: Bridge output uses the same connection row shape and dedupe path as existing service rows (`scripts/lib/hermes-dev-bridge.ts`).
* Error information boundaries: Probe output and command paths are not copied into connection rows (`scripts/lib/hermes-dev-bridge.ts`).

***

### Task T009 - Add skipped-probe parser tests

**Started**: 2026-07-03 02:56 **Completed**: 2026-07-03 02:57 **Duration**: 1 minute

**Notes**:

* Added parser coverage for populated `skippedProbes` connection responses.
* Added compatibility coverage that omitted `skippedProbes` defaults to an empty list.
* Added rejection coverage for non-array skip payloads and malformed skip summary fields.

**Files Changed**:

* `src/lib/__tests__/hermes-types.test.ts` - Added skipped-probe parser coverage.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T009 evidence.

**Verification**:

* Command/check: `bunx vitest run src/lib/__tests__/hermes-types.test.ts`
  * Result: PASS - parser test file passed with skipped-probe cases.
  * Evidence: Vitest reported 1 test file passed and 8 tests passed.
* UI product-surface check: N/A - parser tests only.
* UI craft check: N/A - parser tests only.

**BQC Fixes**:

* Contract alignment: Tests now lock the expanded connection response contract and stale/old response default behavior (`src/lib/__tests__/hermes-types.test.ts`).

***

### Task T008 - Extend connection body parser with skipped probe summaries

**Started**: 2026-07-03 02:55 **Completed**: 2026-07-03 02:56 **Duration**: 1 minute

**Notes**:

* Added `HermesSkippedConnectionProbeSummary` with `id`, `name`, and `reason` fields.
* Added `skippedProbes` to `HermesConnectionsBody` as a separate browser contract list instead of overloading connection status rows.
* Kept compatibility with old connection bodies by defaulting omitted `skippedProbes` to an empty list.

**Files Changed**:

* `src/lib/hermes-types.ts` - Added skipped-probe browser types and parser validation/defaulting.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T008 evidence.

**Verification**:

* Command/check: `bunx vitest run src/lib/__tests__/hermes-types.test.ts`
  * Result: PASS - existing parser coverage still passes with the expanded contract.
  * Evidence: Vitest reported 1 test file passed and 8 tests passed.
* Command/check: `sed -n '140,190p' src/lib/hermes-types.ts && sed -n '780,805p' src/lib/hermes-types.ts`
  * Result: PASS - type and parser inspection confirms `skippedProbes` defaults to `[]` when omitted.
  * Evidence: `HermesConnectionsBody` includes `skippedProbes` and `parseHermesConnectionsResponse()` maps the optional array through `parseSkippedConnectionProbe`.
* UI product-surface check: N/A - parser contract only.
* UI craft check: N/A - parser contract only.

**BQC Fixes**:

* Contract alignment: The expanded parser remains backward-compatible for older bodies while validating the new skipped-probe array shape (`src/lib/hermes-types.ts`).

***

### Task T007 - Add probe helper tests

**Started**: 2026-07-03 02:52 **Completed**: 2026-07-03 02:55 **Duration**: 3 minutes

**Notes**:

* Added focused unit coverage for successful probes, missing CLIs, non-zero exits, timeouts, thrown process errors, cache hit, cache expiry, availability-keyed cache refresh, ignored fake output, and exact allowlist boundaries.
* Used injected resolver, injected process runner, and controlled clock so tests do not require external CLIs or live credentials.
* Verified output-like fake runner fields containing private strings are not returned by the helper.

**Files Changed**:

* `scripts/lib/__tests__/hermes-connection-probes.test.ts` - Added unit tests for probe execution, cache behavior, no-output behavior, and allowlist boundaries.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T007 evidence.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-connection-probes.test.ts`
  * Result: PASS - new probe helper tests passed.
  * Evidence: Vitest reported 1 test file passed and 6 tests passed.
* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the helper and tests.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* UI product-surface check: N/A - backend helper tests only.
* UI craft check: N/A - backend helper tests only.

**BQC Fixes**:

* External dependency resilience: Tests prove missing, non-zero, timeout, and thrown process failures resolve to controlled status-only results (`scripts/lib/__tests__/hermes-connection-probes.test.ts`).
* Error information boundaries: Tests prove fake stdout/stderr and thrown private details are absent from returned probe results (`scripts/lib/__tests__/hermes-connection-probes.test.ts`).
* Contract alignment: Tests prove injected definitions must match the exact built-in allowlist before resolution or process execution runs (`scripts/lib/__tests__/hermes-connection-probes.test.ts`).

***

### Task T006 - Add 30 second status-only probe cache

**Started**: 2026-07-03 02:51 **Completed**: 2026-07-03 02:52 **Duration**: 1 minute

**Notes**:

* Added a 30 second in-memory probe cache using keys derived from probe ID and command availability only.
* Cached entries contain cloned `HermesConnectionProbeResult` objects with service ID, name, slug, status, and reason only.
* Added a narrow `clearHermesConnectionProbeCache()` helper for tests and repeated bridge checks.

**Files Changed**:

* `scripts/lib/hermes-connection-probes.ts` - Added status-only cache, TTL handling, cache reset helper, and cloned cache reads/writes.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T006 evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the cache implementation.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* Command/check: `sed -n '1,260p' scripts/lib/hermes-connection-probes.ts`
  * Result: PASS - cache implementation inspected.
  * Evidence: Cache key is `${probe.id}:${isAvailable ? "available" : "missing"}` and entries store only `HermesConnectionProbeResult`.
* UI product-surface check: N/A - backend helper cache only.
* UI craft check: N/A - backend helper cache only.

**BQC Fixes**:

* State freshness on re-entry: Expired cache entries are deleted and recomputed after the 30 second TTL (`scripts/lib/hermes-connection-probes.ts`).
* Error information boundaries: Cache entries exclude command paths, stdout, stderr, env values, account IDs, emails, and tokens (`scripts/lib/hermes-connection-probes.ts`).

***

### Task T005 - Implement non-shell no-output probe execution

**Started**: 2026-07-03 02:50 **Completed**: 2026-07-03 02:51 **Duration**: 1 minute

**Notes**:

* Added default probe process execution with `spawn()` using `shell: false`, `stdio: "ignore"`, and `windowsHide: true`.
* Added timeout cleanup that kills the child process and clears the timer through the shared settle path.
* Added status-only mapping for missing CLI, success, non-zero exit, timeout, and thrown process errors.
* Kept probe output out of the helper result shape; stdout and stderr are never captured by the default runner.

**Files Changed**:

* `scripts/lib/hermes-connection-probes.ts` - Added CLI resolution, no-output process runner, timeout cleanup, and status-only probe execution.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T005 evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the probe runner and execution flow.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0.
* Command/check: `sed -n '1,220p' scripts/lib/hermes-connection-probes.ts`
  * Result: PASS - runner implementation inspected.
  * Evidence: Runner uses non-shell `spawn`, ignored stdio, timeout kill, and no stdout/stderr listeners or output fields.
* UI product-surface check: N/A - backend helper execution only.
* UI craft check: N/A - backend helper execution only.

**BQC Fixes**:

* Resource cleanup: Timeout cleanup and child-process kill behavior are part of the shared settle path (`scripts/lib/hermes-connection-probes.ts`).
* External dependency resilience: CLI probes have bounded timeouts and controlled failure statuses instead of unbounded waits (`scripts/lib/hermes-connection-probes.ts`).
* Error information boundaries: Process errors map to status-only metadata and do not expose command output (`scripts/lib/hermes-connection-probes.ts`).

***

### Task T004 - Create allowlisted connection probe definitions

**Started**: 2026-07-03 02:49 **Completed**: 2026-07-03 02:50 **Duration**: 1 minute

**Notes**:

* Created the Hermes connection probe helper module with explicit GitHub, Google Workspace, Linear, and Spotify probe definitions.
* Kept each probe definition to a fixed command plus argv array: `gh auth status`, `gws auth status`, `linear whoami`, and `spotify auth status`.
* Added a helper that accepts only exact allowlisted command/argv combinations before execution code is added.

**Files Changed**:

* `scripts/lib/hermes-connection-probes.ts` - Added probe definitions, result/status types, option types, and exact allowlist matching.
* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T004 evidence.

**Verification**:

* Command/check: `bun run typecheck:scripts`
  * Result: PASS - script TypeScript project accepts the new helper types.
  * Evidence: Command completed with `tsc --noEmit -p tsconfig.scripts.json` and exit code 0 after widening the internal allowlist map to `ReadonlyMap<string, HermesConnectionProbeDefinition>`.
* Command/check: `sed -n '1,140p' scripts/lib/hermes-connection-probes.ts`
  * Result: PASS - definition inspection confirms exact argv arrays.
  * Evidence: File contains `gh` with `["auth", "status"]`, `gws` with `["auth", "status"]`, `linear` with `["whoami"]`, and `spotify` with `["auth", "status"]`.
* UI product-surface check: N/A - backend helper definitions only.
* UI craft check: N/A - backend helper definitions only.

**BQC Fixes**:

* Contract alignment: Fixed the internal allowlist map key type so runtime string IDs from injected definitions typecheck against the allowlist (`scripts/lib/hermes-connection-probes.ts`).

***

### Task T003 - Inspect current Hermes connection owners

**Started**: 2026-07-03 02:48 **Completed**: 2026-07-03 02:49 **Duration**: 1 minute

**Notes**:

* Confirmed `scripts/lib/hermes-dev-bridge.ts` owns `GET /__hermes_connections`, connection sorting, `kind:slug` duplicate suppression, provider readiness rows, auth.json provider rows, gateway env rows, generic env-service rows, and memory rows.
* Confirmed `scripts/lib/tool-detection.ts` already provides CLI path resolution through `resolveRuntimeCli()` and does not need broad command execution changes.
* Confirmed `scripts/lib/hermes-provider-readiness.ts` owns provider alias/key mapping and generic env provider suppression.
* Confirmed `src/lib/hermes-types.ts` owns the browser parser for `HermesConnectionsBody`.
* Confirmed `src/components/hermes/hermes-connections.tsx` owns the connection panel product surface and filter behavior.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded T003 inspection evidence.

**Verification**:

* Command/check: `sed -n '1660,1785p' scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - current connection endpoint implementation inspected.
  * Evidence: `readHermesConnections()` builds safe rows from config, `.env`, `auth.json`, gateway tokens, generic service env keys, and memory.
* Command/check: `sed -n '1,260p' scripts/lib/tool-detection.ts`
  * Result: PASS - CLI resolution helper inspected.
  * Evidence: `resolveRuntimeCli()` returns only availability, source, and command path data.
* Command/check: `sed -n '1,320p' src/lib/hermes-types.ts && sed -n '1,320p' src/components/hermes/hermes-connections.tsx`
  * Result: PASS - parser and UI owner inspected.
  * Evidence: `parseHermesConnectionsResponse()` validates the browser contract and `HermesConnections` renders the connection strip.
* UI product-surface check: PASS - inspected connection panel implementation; current product copy does not expose raw bridge diagnostics.
* UI craft check: PASS - inspected existing component pattern for dense card stats, filters, and connection cards; next UI edit will use the same panel/card rhythm.

***

### Task T002 - Run focused baseline tests before edits

**Started**: 2026-07-03 02:48 **Completed**: 2026-07-03 02:48 **Duration**: 1 minute

**Notes**:

* Ran the required focused bridge, parser, hook, and component baseline suite before production source edits.
* Confirmed the existing tests pass before introducing connection probe changes.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Recorded baseline test evidence.

**Verification**:

* Command/check: `bunx vitest run 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`
  * Result: PASS - focused baseline suite passed.
  * Evidence: Vitest reported 4 test files passed and 130 tests passed.
* UI product-surface check: N/A - baseline tests only.
* UI craft check: N/A - baseline tests only.

***

## Task Log

### 2026-07-03 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

***

### Task T001 - Verify handoff artifacts and connection probe scope

**Started**: 2026-07-03 02:47 **Completed**: 2026-07-03 02:47 **Duration**: 1 minute

**Notes**:

* Confirmed Session 01 baseline invariants require semantic ports into existing AI OS owners and browser-safe diagnostics.
* Confirmed Session 02 provider readiness summary added safe provider aliases, configured summaries, and no-leak model/provider bridge behavior.
* Confirmed Session 06 MoA save endpoint summary completed the prior admin bridge work and left Session 07 ready for a read-only connection expansion.
* Confirmed analyzer state resolves current session to `phase40-session07-connection-probe-parity`, with no monorepo package context.
* Confirmed Session 07 scope is limited to allowlisted GitHub, Google Workspace, Linear, and Spotify CLI probes; Notion and Airtable remain env-scanned token-only checks; Hermes MCP probing is skipped with a browser-safe rationale.

**Files Changed**:

* `.spec_system/specs/phase40-session07-connection-probe-parity/implementation-notes.md` - Created session progress log and recorded T001 evidence.

**Verification**:

* Command/check: `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.11-codex/skills/apex-spec/scripts/analyze-project.sh --json; fi`
  * Result: PASS - current session resolved and phase state loaded.
  * Evidence: Output reported `current_session` as `phase40-session07-connection-probe-parity`, `current_session_dir_exists` true, and `monorepo` null.
* Command/check: `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/check-prereqs.sh --json --env; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.11-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env; fi`
  * Result: PASS - environment prerequisites are available.
  * Evidence: Output reported `overall` pass for `.spec_system`, `jq`, and `git`.
* Command/check: `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/check-prereqs.sh --json --tools "bun,bunx"; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.11-codex/skills/apex-spec/scripts/check-prereqs.sh --json --tools "bun,bunx"; fi`
  * Result: PASS - required runtime tools are available.
  * Evidence: Output reported Bun and Bunx version `1.3.14`.
* Command/check: `sed -n '1,220p' .spec_system/specs/phase40-session02-models-and-provider-readiness/IMPLEMENTATION_SUMMARY.md`
  * Result: PASS - handoff artifact exists and confirms provider readiness/no-leak foundation.
  * Evidence: Summary lists provider alias, configured-provider, MoA discovery, parser, hook, and component coverage completed in Session 02.
* Command/check: `sed -n '1,180p' .spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md && sed -n '1,180p' .spec_system/specs/phase40-session06-moa-save-endpoint/IMPLEMENTATION_SUMMARY.md`
  * Result: PASS - dependency handoffs exist and align with Session 07 scope.
  * Evidence: Session 01 documents semantic port invariants; Session 06 documents completed MoA save endpoint and bridge handoff.
* UI product-surface check: N/A - setup artifact verification only.
* UI craft check: N/A - setup artifact verification only.

***


---

# 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/implementation-notes.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.