Repository navigation
docs(conversations-recovery): document non-graceful ACP writer recovery - #12268
Merged
yiliang114 merged 1 commit intoSep 24, 2026
Merged
yiliang114 merged 1 commit into
yiliang114 merged 1 commit into
Conversation
yiliang114
approved these changes
Sep 24, 2026
yiliang114
left a comment
yiliang114
left a comment
Collaborator
There was a problem hiding this comment.
Docs-only runbook addition, and the guidance is consistent with the fencing model described in the preceding steps: a detached ACP writer child outlives a SIGKILLed/OOM-killed daemon and keeps holding the lease, so fencing the daemon alone does not clear the fence — the new paragraph closes exactly that gap, including the right boundary note that a reboot / new PID namespace is a different identity case rather than evidence a writer survived. The supervisor guidance (record ACP descendants before an orderly stop) is the correct way to keep this manual path rare.
CI green, already approved by the bot. Approving; this is ready to merge.
yiliang114
added this pull request to the merge queue
Sep 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Documents the same-boot non-graceful shutdown case in which a daemon killed by SIGKILL or an OOM event can leave a detached ACP writer child alive and holding the session lease, and connects that case directly to the existing recovery instruction to fence every possible writer.
It also adds deployment guidance: wrappers and supervisors should record ACP descendants before an orderly stop and include them in the stop/fence operation, so normal shutdown can reclaim them and manual recovery remains reserved for genuinely non-graceful exits.
The wording deliberately keeps reboot or a restart into a new PID namespace as a separate identity-boundary case. It does not claim that a reboot leaves a live writer child, and it does not publish lock-record fields that triage reserved for a maintainer decision.
Why it's needed
The recovery procedure already says to fence detached ACP children, but the consequence of killing only the daemon is easy to miss during an incident. Naming the same-boot SIGKILL/OOM case tells operators why the child must be fenced before retrying recovery or handling residual artifacts, while preserving the existing fail-closed safety boundary.
Reviewer Test Plan
How to verify
Read the residual-lock recovery procedure and confirm that a same-boot SIGKILL or OOM kill is described as potentially leaving a detached ACP writer alive and holding the lease. Confirm that the procedure requires fencing that child before continuing and does not suggest retrying around or removing the lock. Confirm that reboot or a new PID namespace is described as a distinct identity-boundary case, and that wrapper/supervisor guidance covers ACP descendants during orderly shutdown.
Evidence (Before & After)
N/A — documentation-only change.
Tested on
Environment (optional)
N/A — documentation-only; no runtime dependencies or behavior changed.
Risk & Scope
Linked Issues
Fixes #12214
中文说明
这个 PR 做了什么
补充同一 boot 下的非正常关机场景：daemon 因 SIGKILL 或 OOM 事件被终止后，detached ACP writer 子进程可能仍然存活并继续持有 session lease；同时把这一场景直接连接到现有的“fence every possible writer”恢复指引。
补充部署侧指引：wrapper 和 supervisor 应在有序停止前记录 ACP descendants，并在停止/fence 操作中一并处理它们，使正常关机能够回收这些进程，把人工恢复保留给确实非正常退出的情况。
文案有意把 reboot 或重启进入新的 PID namespace 保留为独立的 identity-boundary 场景；不会声称 reboot 会留下存活的 writer child，也不会公开 triage 明确留给 maintainer 决策的 lock record 字段。
为什么需要
现有恢复流程已经要求 fence detached ACP children，但在事故处理中，单独终止 daemon 的后果很容易被忽略。明确写出同一 boot 下 SIGKILL/OOM 的场景，可以说明为什么必须先 fence 该 child，才能继续重试恢复或处理残留 artifact，同时保留现有的 fail-closed 安全边界。
评审者测试计划
如何验证
阅读 residual-lock recovery 流程，确认其中明确说明同一 boot 下的 SIGKILL 或 OOM kill 可能留下仍存活并持有 lease 的 detached ACP writer。确认流程要求在继续前 fence 该 child，且没有建议通过重试或移除 lock 来绕过 fence。确认 reboot 或新的 PID namespace 被描述为独立的 identity-boundary 场景，并确认 wrapper/supervisor 指引覆盖有序停止期间的 ACP descendants。
证据（修改前后）
N/A —— 纯文档改动。
测试环境
环境（可选）
N/A —— 纯文档改动；没有运行时依赖或行为变化。
风险与范围
关联 Issue
Fixes #12214