mcp-orphan-guard wired three ways — CC SessionStart + Oriz-McpOrphanGuard task + sync-agent-configs belt+braces

decision Mon Jul 06 2026 00:00:00 GMT+0000 (Coordinated Universal Time) mcpperformancefleetagentorphanhookscheduled-taskbelt-bracessessionstart

mcp-orphan-guard wired three ways

Audit findings (2026-07-06)

After yesterday's 194 GB commit hang, the orphan-kill gate is now spread across 3 layers:

CC SessionStart hook — ~/.claude/settings.json SessionStart block already invokes pwsh -NoProfile -File C:/D/oriz/scripts/mcp-orphan-guard.ps1 with 30s timeout, alongside the existing memory-pull and cavemem hooks.
Oriz-McpOrphanGuard scheduled task — registered, Ready. Action: pwsh.exe -NoProfile -WindowStyle Hidden -File "C:\d\oriz\scripts\mcp-orphan-guard.ps1". Trigger: AtLogOn + Daily 09:00.
sync-agent-configs.ps1 belt+braces patch — NEW. One-line & "$PSScriptRoot\mcp-orphan-guard.ps1" call inserted before the final Write-Host "OK: agent configs synced from $srcRoot". Wrapped in try/catch so a fail in the sweep never breaks the sync.

All 3 layers invoke the same idempotent mcp-orphan-guard.ps1.

Why belt+braces

The script is documented idempotent — re-running within seconds has no extra kill effect (orphan list is recomputed each sweep; alive-with-agent processes re-classify correctly).
Layer 1 fires on every Claude Code session start — fastest response to a fresh orphan spawn attached to a child.
Layers 2 + 3 both fire on AtLogOn + Daily 09:00. If one task ever gets disabled (registry edit, accidental Unregister-ScheduledTask), the other still runs.
Layer 3 is the user-policy fallback per the related rule: "SessionStart hook (or Oriz-SyncAgentConfigs task) may inject an orphan-node kill".

Triggers summary

Layer	Trigger	Latency
1	CC SessionStart hook	Real, on every session start
2	AtLogOn	At user logon
2	Daily 09:00	Once per day
3	AtLogOn (via Oriz-SyncAgentConfigs)	At user logon
3	Daily 09:00 (via Oriz-SyncAgentConfigs)	Once per day

Kilo + OpenCode gap

Kilo and OpenCode config schemas have no hooks / startup / init field. Grep on the live configs (~/.config/kilo/kilo.jsonc, ~/.config/opencode/opencode.jsonc) returned NONE. So no true per-session hook is possible for those agents. The periodic scheduled-task fallback is the prescribed answer for non-CC agents per the lazy-load rule.

Not in scope today

Agents installed on this machine: Claude Code (4 sessions), Kilo Code (1), OpenCode (4). The other 5 fleet members (Antigravity, GH Copilot CLI, Freebuff, Qwen Code CLI, Cline) are referenced in AGENTS.md but not running here. They would inherit the same belt+braces pattern via sync-mcp-to-agents.mjs + Oriz-SyncAgentConfigs once installed.

Verification commands

# Layer 1 — CC hook still in place
Select-String -Path ~\.claude\settings.json -Pattern 'mcp-orphan-guard'

# Layer 2 — scheduled task action
Get-ScheduledTask Oriz-McpOrphanGuard | ForEach-Object { ($_.Actions | Select-Object -First 1) }

# Layer 3 — belt+braces addition in sync-agent-configs.ps1
Select-String -Path C:\d\oriz\scripts\sync-agent-configs.ps1 -Pattern 'Belt\+braces orphan-kill'

# Manual sweep (idempotent; safe to re-run)
pwsh -NoProfile -File C:\D\oriz\scripts\mcp-orphan-guard.ps1

# Tail the append-mode log
Get-Content "$env:LOCALAPPDATA\oriz\mcp-orphan-guard.log" -Tail 30

Why not extend sync-mcp-to-agents.mjs

The umbrella fanout script writes MCP server definitions only. It does not (and cannot, given current schema support) write hook fields into kilo/opencode configs. Hook wiring for those agents remains a unified-task fallback for now.

Cross-refs

mcp-orphan-node-army-commit-hang-2026-07-06 — the 194 GB hang, root cause, and original fix
mcp-lazy-load-mandatory-2026-07-06 — prescribed fallback mechanism ("hook or scheduled task")
agent-fleet-parity — every fleet agent gets this
scripts/sync-agent-configs.ps1 — receives Layer 3 patch