feat: harden release smoke and graph inspection

.dev/status/current-handoff.md

@@ -1,7 +1,7 @@
 # agent-memory current handoff
 
 Status: AI-authored draft. Not yet human-approved.
-Last updated: 2026-04-30 22:21 KST
+Last updated: 2026-04-30 23:00 KST
 
 ## Trigger for the next session
 
@@ -16,9 +16,7 @@ read this file first. Do not ask the user to restate context. Verify repo state,
 
 ## Ready-to-say answer
 
-지금 agent-memory는 OSS 기본 메모리 레이어 신뢰도 작업 Priority 1~4의 주요 truth lifecycle 조각, retrieval-eval read-only hardening, protected-main release fallback 자동화를 v0.1.32까지 완료했고, 현재 slice는 release fallback rerun idempotency 보강이야.
-
-최신 검증 완료 릴리스는 v0.1.32야. v0.1.27에서 status transition history, v0.1.28에서 npm wrapper stdin forwarding과 published Hermes hook smoke, v0.1.29에서 fact supersession/replacement relation, v0.1.30에서 `agent-memory review explain fact ...` decision explanation UX, v0.1.31에서 retrieval eval read-only behavior, v0.1.32에서 protected-main release-sync PR/tag/publish automation이 들어갔어. 로컬 Hermes hook도 v0.1.32 runtime으로 업데이트되어 doctor/hook smoke가 통과한 상태야.
+지금 agent-memory는 v0.1.33까지 release fallback rerun idempotency와 Hermes v0.1.33 QA까지 끝났고, 현재 진행 중인 통합 slice는 v0.1.34 후보야. 세 가지를 한 PR로 묶어 진행 중이야: published smoke propagation/backoff hardening, release-sync PR CI validation dispatch, read-only relation graph inspect CLI.
 
 ## Current repo state
 
@@ -35,18 +33,15 @@ Expected GitHub identity:
 Verified base before this slice:
 
 - branch: `main`
-- HEAD: `654c5d8 chore: release v0.1.32 [skip release] (#32)`
-- tag/release: `v0.1.32`
-- GitHub Release: `https://github.com/cafitac/agent-memory/releases/tag/v0.1.32`
-- npm: `@cafitac/agent-memory@0.1.32`
-- PyPI: `cafitac-agent-memory==0.1.32`
-- v0.1.32 published smoke artifact: passed; includes npm/uvx/pipx Hermes hook commands.
-- repo Actions workflow setting: `can_approve_pull_request_reviews=true`, needed so `GITHUB_TOKEN` can create release-sync PRs.
+- latest completed release: `v0.1.33`
+- v0.1.33 included release-sync fallback rerun idempotency.
+- local Hermes hook uses `/Users/reddit/.agent-memory/runtime/v0.1.33/.venv/bin/agent-memory` against `/Users/reddit/.agent-memory/memory.db`.
 
 Active slice/worktree:
 
-- branch: `ci/release-fallback-idempotency`
-- worktree: `/Users/reddit/Project/agent-memory/.worktrees/release-fallback-idempotency`
+- branch: `feat/release-graph-hardening`
+- worktree: `/Users/reddit/Project/agent-memory/.worktrees/release-graph-hardening`
+- intended release after merge: likely `v0.1.34`
 
 Expected local untracked artifacts to preserve in the root checkout:
 
@@ -58,7 +53,7 @@ Expected local untracked artifacts to preserve in the root checkout:
 
 Do not delete or commit these unless the user explicitly asks.
 
-## What is complete through v0.1.32
+## What is complete through v0.1.33
 
 ### Distribution and release automation
 
@@ -68,11 +63,12 @@ Do not delete or commit these unless the user explicitly asks.
 - Published smoke uploads `published-install-smoke-result` JSON artifact with success/failure diagnostics.
 - v0.1.28+ smoke covers npm/npx/npm-exec/uvx/pipx and Hermes hook stdin payload handling.
 - Protected `main` fallback is automated: auto-release creates `release-sync/vX.Y.Z` PR when direct metadata write-back is rejected; after merge, auto-release tags and dispatches publish.
+- v0.1.33 made that fallback safe to rerun when the branch or PR already exists.
 
 ### Runtime adapter readiness
 
 - Hermes bootstrap/doctor/install flow exists and defaults to the conservative preset.
-- This local Hermes setup has agent-memory enabled via `/Users/reddit/.agent-memory/runtime/v0.1.32/.venv/bin/agent-memory` against `/Users/reddit/.agent-memory/memory.db`.
+- This local Hermes setup has agent-memory enabled via `/Users/reddit/.agent-memory/runtime/v0.1.33/.venv/bin/agent-memory` against `/Users/reddit/.agent-memory/memory.db`.
 - Hermes hook fails closed: unavailable DB/schema returns `{}` and exit 0 instead of breaking prompt flow.
 - Conservative preset remains default: small prompt budgets, one top memory, no alternative-memory detail, no reason-code noise.
 - `--preset balanced` is explicit opt-in for more context/noise.
@@ -90,36 +86,98 @@ Do not delete or commit these unless the user explicitly asks.
 - `agent-memory review explain fact ...` explains status, default retrieval visibility, same claim-slot alternatives, replacement chain, and review follow-up commands.
 - Retrieval eval calls the real retrieval path but suppresses retrieval bookkeeping writes (`retrieval_count`, `reinforcement_count`, `last_accessed_at`).
 
-## Current slice: release fallback rerun idempotency
+## Current slice: release/package/graph hardening
+
+User asked to do all three next recommended tasks:
+
+1. Published smoke propagation/backoff improvement.
+2. release-sync PR CI dispatch/status automation.
+3. Graph foundation first safe slice: read-only relation graph inspect CLI.
+
+Current implementation direction:
+
+### Published smoke propagation/backoff
+
+Files:
+
+- `scripts/smoke_published_install.py`
+- `tests/test_published_install_smoke.py`
+- `.github/workflows/publish.yml`
+- `.github/workflows/published-install-smoke.yml`
+
+Behavior:
+
+- Detect resolver/package-index propagation-like failures such as `No solution found`, `No matching distribution found`, npm 404/ETARGET/NOTARGET, and exact `cafitac-agent-memory==X.Y.Z` misses.
+- Apply a separate longer retry budget only for propagation-like failures:
+  - normal attempts remain bounded
+  - propagation attempts can extend with exponential backoff
+- Failure artifacts include registry probe diagnostics:
+  - npm version present/latest
+  - PyPI JSON release present
+  - PyPI simple index mentions version
+  - probe errors
+- `publish.yml` uses `--attempts 12`, `--propagation-attempts 36`, `--propagation-delay-seconds 20`.
+- Manual `published-install-smoke.yml` exposes propagation attempt/delay inputs.
+
+### release-sync PR CI validation dispatch
+
+Files:
 
-Why this slice exists:
+- `.github/workflows/auto-release.yml`
+- `tests/test_release_workflows.py`
 
-- During the first v0.1.32 live fallback run, GitHub Actions created `release-sync/v0.1.32` but failed to create the PR because the repository Actions setting initially disallowed GitHub Actions from creating PRs.
-- After enabling that setting, rerunning the failed job hit a non-fast-forward branch push because the release-sync branch already existed.
-- The fallback should be safe to rerun after this kind of partial success.
+Behavior:
 
-Planned behavior:
+- When fallback creates a new `release-sync/vX.Y.Z` PR, capture the PR URL.
+- Dispatch `ci.yml` explicitly on `release-sync/vX.Y.Z` with `gh workflow run ci.yml --ref "${RELEASE_SYNC_BRANCH}"`.
+- Comment on the PR explaining that bot-created refs may suppress automatic PR checks and that maintainers should wait for the dispatched `ci.yml` run before merging.
 
-- When protected-main fallback starts, check whether `release-sync/vX.Y.Z` already exists on origin.
-- If the branch exists, reuse it instead of pushing and failing with non-fast-forward.
-- Check whether an open PR already exists for the release-sync branch.
-- If the PR exists, log the URL and exit successfully instead of opening a duplicate PR.
-- If neither exists, keep the existing branch push + `gh pr create` behavior.
+### read-only relation graph inspect CLI
 
-Implementation direction:
+Files:
 
-- Update `.github/workflows/auto-release.yml` fallback step with `git ls-remote --heads` branch detection.
-- Add `gh pr list --head ... --state open --json url --jq '.[0].url // empty'` before `gh pr create`.
-- Keep the direct path and release-sync tag/publish follow-up unchanged.
-- Add/keep tests in `tests/test_release_workflows.py` proving idempotency markers exist in the workflow.
+- `src/agent_memory/api/cli.py`
+- `src/agent_memory/storage/sqlite.py`
+- `tests/test_cli.py`
+- `README.md`
+
+New command:
+
+```bash
+agent-memory graph inspect <db_path> <start_ref> --depth 1 --limit 100
+```
+
+Example:
+
+```bash
+agent-memory graph inspect ~/.agent-memory/memory.db fact:1 --depth 2 --limit 50
+```
+
+Behavior:
+
+- Traverses stored `Relation` edges only.
+- JSON output includes:
+  - `kind: relation_graph_inspection`
+  - `start_ref`
+  - `depth`
+  - `limit`
+  - `read_only: true`
+  - `nodes`
+  - `edges`
+  - `truncated`
+- Does not change retrieval behavior.
+- Does not mutate memory state.
+- Intended as the first safe graph-foundation slice before default retrieval graph traversal.
 
 ## Verification checklist for this slice
 
 Run from the active worktree:
 
 ```bash
-uv run pytest tests/test_release_workflows.py -q
 uv run pytest tests/test_published_install_smoke.py -q
+uv run pytest tests/test_release_workflows.py -q
+uv run pytest tests/test_cli.py::test_python_module_cli_graph_inspect_returns_read_only_relation_neighborhood -q
+uv run pytest tests/test_published_install_smoke.py tests/test_release_workflows.py tests/test_cli.py -q
 uv run pytest tests/ -q
 uv run python scripts/check_release_metadata.py
 uv run python scripts/smoke_release_readiness.py
@@ -132,21 +190,22 @@ Before PR, run a static diff secret scan and confirm finding_count 0.
 
 ## PR/release notes
 
-This slice changes only release automation/docs/tests, but it affects the release path and should be treated as a patch release candidate, likely v0.1.33 after PR merge.
+This slice affects release automation, published install smoke, and a new read-only CLI command. Treat it as a patch release candidate, likely v0.1.34 after PR merge.
 
 Expected live verification after merge:
 
-1. PR merge should trigger auto-release and bump metadata to v0.1.33.
+1. PR merge should trigger auto-release and bump metadata to v0.1.34.
 2. Protected `main` should trigger fallback.
-3. Fallback should create `release-sync/v0.1.33` PR or reuse it if a partial rerun already created it.
-4. Merge the release-sync PR.
-5. Confirm release-sync follow-up creates tag `v0.1.33`, dispatches publish, and published smoke passes.
-6. Verify GitHub Release/npm/PyPI/published-install-smoke artifact.
-7. Update local Hermes runtime to v0.1.33 only after package release is verified.
+3. Fallback should create `release-sync/v0.1.34` PR and dispatch `ci.yml` on that branch.
+4. Wait for the dispatched CI run before merging release-sync PR.
+5. Merge the release-sync PR.
+6. Confirm release-sync follow-up creates tag `v0.1.34`, dispatches publish, and published smoke passes.
+7. Verify GitHub Release/npm/PyPI/published-install-smoke artifact.
+8. Update local Hermes runtime to v0.1.34 only after package release is verified.
 
 ## Next likely slices after this
 
-1. Published smoke propagation handling improvement: make first-run simple-index lag less noisy.
-2. Actual Hermes dogfood observations and noise/latency notes.
-3. Graph foundation read-only slice: graph inspection CLI or bounded relation traversal eval fixtures.
+1. Actual Hermes dogfood observations and noise/latency notes.
+2. Expand graph inspection with node metadata/status summaries, still read-only.
+3. Later graph retrieval eval fixtures before any default graph expansion.
 4. PyPI Trusted Publisher later; user deferred it.

.github/workflows/auto-release.yml

@@ -126,12 +126,17 @@ jobs:
           ## Next automation
           Publish workflow will run after the release sync PR is merged and the tag is pushed.
           EOF
-          gh pr create \
+          release_sync_pr_url=$(gh pr create \
             --repo "${{ github.repository }}" \
             --base main \
             --head "${RELEASE_SYNC_BRANCH}" \
             --title "chore: release ${{ steps.bump.outputs.tag }} [skip release]" \
-            --body-file /tmp/release-sync-pr.md
+            --body-file /tmp/release-sync-pr.md)
+          echo "Release sync PR created: ${release_sync_pr_url}"
+          gh workflow run ci.yml --ref "${RELEASE_SYNC_BRANCH}"
+          gh pr comment "${release_sync_pr_url}" \
+            --repo "${{ github.repository }}" \
+            --body "Release sync validation CI was dispatched for ${RELEASE_SYNC_BRANCH}. Because this PR is created by GitHub Actions, automatic PR checks may be suppressed; wait for the dispatched `ci.yml` run before merging."
 
       - name: Dispatch publish workflow for bot-created tag
         if: steps.push_release.outputs.release_sync_required == 'false'

.github/workflows/publish.yml

@@ -149,8 +149,10 @@ jobs:
           VERSION="${GITHUB_REF_NAME#v}"
           uv run python scripts/smoke_published_install.py \
             --version "$VERSION" \
-            --attempts 36 \
+            --attempts 12 \
             --delay-seconds 10 \
+            --propagation-attempts 36 \
+            --propagation-delay-seconds 20 \
             --output-json .artifacts/published-install-smoke.json
 
       - name: Upload published install smoke result

.github/workflows/published-install-smoke.yml

@@ -12,10 +12,15 @@ on:
         required: false
         default: '18'
         type: string
-      delay_seconds:
-        description: 'Delay between retry attempts'
+      propagation_attempts:
+        description: 'Longer retry budget for propagation-like resolver failures'
         required: false
-        default: '10'
+        default: '36'
+        type: string
+      propagation_delay_seconds:
+        description: 'Base exponential backoff delay for propagation-like resolver failures'
+        required: false
+        default: '20'
         type: string
 
 jobs:
@@ -50,7 +55,9 @@ jobs:
           uv run python scripts/smoke_published_install.py \
             --version "${{ inputs.version }}" \
             --attempts "${{ inputs.attempts }}" \
-            --delay-seconds "${{ inputs.delay_seconds }}" \
+            --delay-seconds 10 \
+            --propagation-attempts "${{ inputs.propagation_attempts }}" \
+            --propagation-delay-seconds "${{ inputs.propagation_delay_seconds }}" \
             --output-json .artifacts/published-install-smoke.json
 
       - name: Upload published install smoke result

README.md

@@ -94,6 +94,15 @@ agent-memory review explain fact "$DB" 1
 
 `review explain` combines the current status, default retrieval visibility, transition history, same claim-slot alternatives, and replacement chain into one decision context so a reviewer can see why a stale or conflicting fact is hidden.
 
+For read-only relation graph inspection, use `graph inspect`. This is an operator/debug view over stored `Relation` edges; it does not change retrieval behavior or mutate memory state:
+
+```bash
+agent-memory graph inspect "$DB" fact:1 --depth 1
+agent-memory graph inspect "$DB" fact:1 --depth 2 --limit 50
+```
+
+The JSON output includes the start ref, visited node refs, relation edges, traversal depth per edge, and a `read_only: true` marker. It is intended as a safe graph-foundation slice before enabling any broader graph traversal in default retrieval.
+
 ## Hermes quickstart
 
 For most Hermes users:
@@ -246,9 +255,9 @@ uv run pytest tests/test_published_install_smoke.py -q
 npm pack --dry-run
 ```
 
-After a release publishes, the `published-install-smoke` workflow verifies the exact npm/PyPI version through npm registry lookup, `npx`, `npm exec`, `uvx`, and `pipx`. Maintainers can also run it manually with `gh workflow run published-install-smoke.yml -f version=<version>`.
+After a release publishes, the `published-install-smoke` workflow verifies the exact npm/PyPI version through npm registry lookup, `npx`, `npm exec`, `uvx`, and `pipx`. Maintainers can also run it manually with `gh workflow run published-install-smoke.yml -f version=<version>`. The smoke script treats early resolver/package-index misses as propagation-like failures and applies a longer exponential backoff before failing; failure artifacts include npm/PyPI registry probe diagnostics so maintainers can tell whether metadata is visible while installers are still stale.
 
-Release automation expects protected `main`: if the auto-release workflow cannot push its bumped metadata commit directly, it opens a `release-sync/vX.Y.Z` PR instead. After that PR is merged, the same workflow tags the synced version and dispatches `publish.yml`, keeping the release path automated without requiring a permanent branch-protection bypass. The fallback is safe to rerun: if the `release-sync/vX.Y.Z` branch or PR already exists, the workflow reuses it instead of failing on a non-fast-forward push or opening a duplicate PR.
+Release automation expects protected `main`: if the auto-release workflow cannot push its bumped metadata commit directly, it opens a `release-sync/vX.Y.Z` PR instead. After that PR is merged, the same workflow tags the synced version and dispatches `publish.yml`, keeping the release path automated without requiring a permanent branch-protection bypass. The fallback is safe to rerun: if the `release-sync/vX.Y.Z` branch or PR already exists, the workflow reuses it instead of failing on a non-fast-forward push or opening a duplicate PR. When it creates a new release-sync PR, it also dispatches `ci.yml` on that bot-created branch and comments with the validation handoff because GitHub can suppress automatic PR checks for bot-created refs.
 
 Useful source-checkout commands: