Skip to content

fix(memories): repair dangling references and diagnostic false positives - #21

Merged
wrightpt merged 2 commits into
mainfrom
agent/dangling-supersedes-cleanup
Aug 5, 2026
Merged

wrightpt merged 2 commits into
mainfrom
agent/dangling-supersedes-cleanup

Conversation

@wrightpt

@wrightpt wrightpt commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Summary

  • clear surviving supersedes, parentId, and relatedIds references after governance deletion
  • let diagnostics and heal identify and repair existing dangling references with fresh reads under keyed locks
  • preserve explicit human, approval, manual, and checkpoint gates when dependencies are complete
  • report project-scope coverage honestly when unscoped memories cannot be inferred automatically

Validation

  • npm test: 160 files, 1703 tests passed
  • npm run build: passed
  • git diff --check origin/main...HEAD: passed

Activation boundary

Merge only updates the repository. It does not rebuild or restart the workstation AgentMemory service, invoke heal, rewrite live memories, or activate the local changes.

pi-agent added 2 commits August 4, 2026 21:39
…e + heal

Root cause (D2): mem::governance-delete and mem::governance-bulk deleted a
memory without clearing supersedes/parentId/relatedIds back-references in
*other* memories, so every delete minted new memory-missing-supersedes
warnings. The heal path could not repair them either (the warn was
fixable=false and no prune branch existed).

Changes (code-only; no live data touched, no restart/deploy):
- src/state/memory-utils.ts: add pure stripMemoryReferences() that drops
  references to a given id set from supersedes/parentId/relatedIds and
  reports what was removed. Shared by governance and diagnostics.
- src/functions/governance.ts: governance-delete and governance-bulk now
  call clearDanglingMemoryReferences() on surviving memories after a
  delete, returning repairedReferrers + removedReferences in the result
  and audit details. Indexes untouched (ref fields are not searchable).
- src/functions/diagnostics.ts:
  * memory-missing-supersedes warn is now fixable=true.
  * add memory-missing-parent and memory-missing-related warn detection.
  * add a memories heal branch that prunes dangling supersedes/parentId/
    relatedIds (dry-run supported), audited as reason
    "dangling-memory-reference-prune".
- Honest project-coverage messaging (D3): the diagnostic no longer
  blindly prescribes infer-memory-projects. It splits the unscoped count
  into session-linked (inferable) vs session-less (ambiguous; the
  migration returns them unchanged), and says so explicitly — verified
  live that infer-memory-projects is updated=0/ambiguous=128 here.

Tests: +8 in test/diagnostics.test.ts and test/governance.test.ts
covering delete cleanup (single + bulk), heal prune (apply + dry-run),
the new parentId/relatedIds warns, and the honest coverage messages.
Full suite: 1699 passed (160 files). Build: tsdown OK.

Not pushed, not merged, not deployed, not activated. The diverged local
main (ahead 2 / behind 13) is untouched. The running engine build is
unchanged; these changes take effect only after a supervisor-authorized
build + systemctl restart agentmemory.service, at which point the
existing dangling references can be pruned via
mem::heal {categories:["memories"]} (dry-run first).

Refs: AgentMemory action act_msfdnoby_4609034b3c0f (workstation)
Code-only supervisor review corrections for 6c27da2. No live mutation,
no restart/deploy.

(1) blocked-deps-done false-positive guard (the rebound root cause):
- src/functions/actions.ts: export hasExplicitNonDependencyGate() — true
  when an action is held by blockedReason / awaitingHuman / pending-or-
  rejected approval / an unsatisfied gated_by checkpoint (i.e. NOT by its
  requires-deps alone).
- diagnostics.ts diagnosis: only flag blocked-deps-done (fixable) when the
  block is dependency-only; explicitly-gated actions are intentionally
  blocked and are no longer flagged.
- diagnostics.ts heal: the blocked-deps-done branch now skips explicitly-
  gated actions (returns false -> skipped), so heal no longer churns
  revisions or writes a misleading newStatus=pending audit for actions
  legacyStatusFor would immediately re-block.

(2) Honest project-coverage fixability: fixable = inferableCount > 0. When
  every unscoped memory lacks sessionIds the infer-memory-projects
  migration is a no-op, so the finding is not auto-fixable.

(3) clearDanglingMemoryReferences concurrency: each survivor is now
  repaired under its per-memory keyed lock (mem:memory:<id>) with a fresh
  read immediately before strip/write, so a concurrent survivor update is
  preserved instead of clobbered by a stale snapshot.

(4) Removed the untracked node_modules symlink from the worktree.

Tests (+4): diagnose "explicit human/approval/blockedReason gates not
flagged"; heal "does not unblock an explicit-gate action"; governance
concurrency "preserves a concurrent survivor update" and "does not clobber
a concurrently-corrected survivor" (both fail on the pre-fix code).
Project-coverage tests gained fixable assertions (zero-candidate=false,
mixed=true). Full suite 1703 passed (160 files); tsdown build OK. git
status clean (node_modules symlink removed).

Not pushed, not merged, not deployed, not activated. REBOUND-INVESTIGATION
conclusions unchanged (the three live actions remain correctly blocked by
their approval gates; this commit just stops flagging/healing them).

Refs: AgentMemory action act_msfdnoby_4609034b3c0f (workstation)
@wrightpt
wrightpt merged commit 5568448 into main Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant