@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-memory-project-docs/SPEC.md

@@ -0,0 +1,133 @@
+# Agent memory 与项目文档 promotion 分层
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前全局文档模型已经收敛出 `docs/specs/**` 与 `docs/solutions/**`，但它们都更偏工程流程与 Agent memory。
+- 若没有额外的 promotion 契约，项目级当前真相会持续埋在碎 spec / solution 中，人类维护者必须沿着任务历史才能理解项目。
+- 先前对 Compound 风格分层的讨论已经明确：仓库内不落 `plans/`，`notes/` 也不作为 canonical knowledge store；真正缺的是“Agent memory -> human-facing project docs”的持续治理能力。
+
+## 目标 / 非目标
+
+### Goals
+
+- 固化文档角色分层：`docs/specs/**` 与 `docs/solutions/**` 继续承担 Agent memory / engineering memory，repo 已建立的人类项目文档 / 入口文档（通常 `docs/**`，也可为根入口文档）承担 human-facing current truth。
+- 在共享工程流程里新增 `project_doc_disposition=none|update|create|defer`，并把它变成 merge-ready 前的显式 gate。
+- 新增 `$project-doc-promote` skill，负责按项目自身文档结构把稳定结论提升到合适的项目文档。
+- 扩展 `$docs-migrate`，使其同时支持历史文档 / 碎 spec / solution 到项目文档的批量 promotion。
+- 统一 PR 正文 `References` 约定：按相关性引用 `Specs`、`Solutions`、`Project Docs`。
+
+### Non-goals
+
+- 不把 `plans/` 恢复成仓库内 artifact。
+- 不把 `notes/` 恢复成 canonical knowledge store。
+- 不给所有项目强制固定同一套 `docs/` 目录骨架。
+
+## 范围（Scope）
+
+### In scope
+
+- `.codex/AGENTS.md` 的全局文档模型、PR 引用与 promotion gate 规则。
+- `skills/project-engineering-workflow/SKILL.md` 及相关 flow skill 的新 gate / 状态字段。
+- workflow PR publication procedure 的 PR `References` 规则。
+- 新 skill `skills/project-doc-promote/`。
+- 扩展 `skills/docs-migrate/` 及其 references。
+- `docs/README.md`、`docs/specs/README.md`、`docs/solutions/README.md` 等人类可读入口说明。
+
+### Out of scope
+
+- 批量重写外部项目仓库的人类文档结构。
+- 为项目文档引入全局固定 taxonomy。
+- 单独新增一个仓库内 `plans/` 文档空间。
+
+## 需求（Requirements）
+
+### MUST
+
+- 全局工程记忆模型继续固定为 `docs/specs/** + docs/solutions/**`，且不恢复 `notes/` / `plans/` 为 canonical。
+- `docs/specs/**` 与 `docs/solutions/**` 必须明确标注为 Agent / 工程流程导向，而不是项目文档替身。
+- 共享工程流程在 merge-ready 前必须完成 `project_doc_disposition=none|update|create|defer` 判定。
+- 若 `project_doc_disposition=update|create`，对应项目文档必须在收口前落盘并形成 `Project文档同步证据=<path@sha>`。
+- 若 `project_doc_disposition=defer`，必须记录 defer 原因、目标文档与后续动作；不能只写“以后再说”。
+- 项目文档的目标路径必须优先服从项目已有 `docs/` 结构；不得强推统一目录骨架。
+- PR 正文在相关时必须显式给出 `Specs`、`Solutions`、`Project Docs` 引用。
+- `$project-doc-promote` 必须只提升稳定项目真相，不得把整段 task log / milestone / review 过程直接复制到项目文档。
+- `$docs-migrate MODE=project-docs` 必须支持“历史迁移 + 批量提升”，且允许多个 spec / solution 汇总到一个项目文档中。
+
+### SHOULD
+
+- 仓库在缺少清晰人类文档入口时，补一个最小 index / overview 文档，便于人类查阅。
+- `skills/README.md` 与 docs 入口文案同步说明新 skill 与新 gate。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 共享工程流程继续以 `specs + solutions` 作为 Agent memory 输入；但在 Step 4 收口前，必须额外判断是否需要把稳定结论 promotion 到项目文档。
+- `project_doc_disposition=none`：本轮没有需要进入人类项目文档的稳定真相。
+- `project_doc_disposition=update`：已有项目文档需要更新。
+- `project_doc_disposition=create`：现有项目文档没有合适承载面，需要新增人类文档。
+- `project_doc_disposition=defer`：已经确认需要 promotion，但本轮因范围或时机原因暂缓；必须留下可执行 defer 记录。
+- PR body 的 `References` 负责把本轮关联的 `Specs`、`Solutions`、`Project Docs` 串起来；`local-merge` 路径虽不创建 PR，也沿用同一引用模型作为统一口径。
+
+### Edge cases / errors
+
+- 若项目现有 `docs/` 结构无法唯一推导 promotion 目标，优先更新现有总览/索引文档；若仍无法确定，再阻断并只问 1 个关键问题。
+- 若历史 spec / solution 中混有大量一次性任务 prose，`project-docs` 迁移只能抽取稳定结论，不能整文照搬。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| project_doc_disposition | workflow field | internal | New | None | codex-global | shared workflow / flow skills | merge-ready 前必须决议 |
+| project-doc-promote | skill | internal | New | None | codex-global | shared workflow / docs tasks | 日常 promotion |
+| docs-migrate project-docs mode | skill mode | internal | Modify | `skills/docs-migrate/references/project-docs-mode.md` | codex-global | docs taxonomy migration | 历史迁移 + 批量提升 |
+| PR References: Specs / Solutions / Project Docs | PR body contract | internal | Modify | `skills/project-engineering-workflow/references/pr-publication-procedure.md` | codex-global | PR flows | 三类引用统一口径 |
+
+## 验收标准（Acceptance Criteria）
+
+- Given 一个任务只更新 agent memory，When 进入 Step 4 收口，Then 可以显式记录 `project_doc_disposition=none` 并继续。
+- Given 一个任务改变了项目级当前真相，When 进入 Step 4 收口，Then 必须先写入或新建合适的项目文档，或者留下完整 `defer` 记录。
+- Given 仓库已有自定义的 `docs/` 结构，When `$project-doc-promote` 或 `$docs-migrate MODE=project-docs` 选择目标文档，Then 必须优先复用现有结构，而不是强制固定 taxonomy。
+- Given 一个 PR 关联了 spec、solution 与项目文档，When workflow PR publication procedure 生成/重写 PR body，Then 相关引用会显式出现在 `References` 中。
+- Given 一个历史 spec / solution 批量收敛到人类项目文档的任务，When 运行 `$docs-migrate MODE=project-docs`，Then 允许多个来源汇总到一个项目文档，但原 spec / solution 仍保留为 Agent memory。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `git diff --check`
+- `rg -n "project_doc_disposition|Project Docs|project-doc-promote|MODE=project-docs" AGENTS.md docs skills`
+- `python3 /Users/ivan/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/project-doc-promote`
+
+### Quality checks
+
+- 项目文档路径与说明不得硬编码全局目录骨架。
+- `specs/solutions` 与 `docs/**` 项目文档的职责表述必须一致。
+
+## Visual Evidence
+
+None
+
+## 方案概述（Approach, high-level）
+
+- 保持 `specs + solutions` 作为工程记忆主轴，不再新增仓库内 `plans` 或恢复 `notes`。
+- 把“需要人类直读的稳定结论”从工程记忆中提升出来，但提升目标路径交给项目自身文档结构决定。
+- 用一个轻量的日常 promotion skill + 一个批量迁移 mode 来分工治理增量与历史积累。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若项目没有任何既有人类文档结构，promotion 目标仍可能需要一次人工判断。
+- 风险：PR flow 与 local-merge flow 若输出字段不同步，会让后续恢复语义产生偏差。
+- 假设：PR 正文继续允许 `Spec:` / `Specs:` 兼容 legacy 写法，同时新增 `Solutions:` 与 `Project Docs:`。
+
+## 参考（References）
+
+- `docs/specs/global-solutions-docs-migrate/SPEC.md`
+- `AGENTS.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- `skills/docs-migrate/SKILL.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/HISTORY.md

@@ -0,0 +1,31 @@
+# Agent VM history
+
+- Memory exhaustion exposed both a 24-GiB logical ceiling and high QEMU resident memory despite free guest pages. The accepted correction adds explicit native live balloon/hotplug without a restart fallback, teaches voluntary downsize after high-memory phases and sets the configurable RAM ratio to 4 (48-GiB ceiling over the unchanged 12-GiB base). Actual CT pressure admission remains enforced for growth; native/guest continuity and partial outcomes remain inspectable. Protocol 4 fails older peers before effects while preserving state/journals. This uses the existing native lifecycle and configurable-overselling decisions.
+
+- Initial live testing exposed Incus 7.5.1's five-second balloon confirmation window: both 2-to-1-GiB and 4-to-2-GiB attempts timed out while guest memory changed without reboot. The errors remain inspectable rather than counted as success. The correction allows one guarded same-target completion attempt for a shrinking balloon still above target within the original operation, preserving both native outcomes and conservative allocation until acknowledgement; growth/hotplug and other uncertain updates remain partial. A larger 12-to-4-GiB test then timed out both immediate attempts while the guest subsequently converged, so the single completion now follows one fixed 45-second wait with all guards checked again; the initial failures remain evidence rather than passing results. The corrected archived control completed an independently observed 12-to-4-to-12-GiB run and direct CLI/cache use; implementation evidence distinguishes native acknowledgement, logical allocation and observed resident memory.
+
+- The retention clarification separates actual task closure from validation, review/CI waits and readiness handoffs. Expected follow-up, including build-cache reuse, keeps the session VM under an effective lease; an actively progressing Agent may explicitly renew within existing limits. PR merge without further VM work, non-PR completion and cancellation trigger normal closure. The accepted [design background](RETENTION-DESIGN.md) now points to the normative Spec and operating Skill; this instruction change does not alter protocol 3 or native expiry/cache semantics.
+
+- The instance-count incident exposed an eight-instance project quota counting stopped caches, while manual GC used the age timer's 24-hour filter. The accepted correction removes the native count ceiling, separates immediate cache eligibility from age selection and upgrades destructive management semantics to protocol 3. CPU/RAM ceilings and valid-lease protection remain unchanged; protocol 3 installation and isolated/direct acceptance passed and are tracked in the implementation companion.
+
+- ADR 0026 supplements the native architecture with separate base budgets and CPU/RAM oversold allocation ceilings, CT-only memory pressure admission and configurable acquire. Protocol 2 retains existing durable state and operation journals; uncertain protocol-1 requests require inspection rather than automatic conversion or replay. Current rollout and acceptance belong to the implementation companion.
+- Protocol 2 was installed from `8b6a376d` after natural drain convergence, with only aggregate Incus CPU/RAM quotas removed. Direct 8-CPU/12-GiB acquire and 4-CPU/8-GiB resize passed; isolated 24-CPU/30-GiB idle startup exceeded the CT-visible capacity under an explicitly separate RAM test ratio. That rollout retained its accepted 60-CPU/24-GiB ceiling.
+
+- Implementation delivery: [PR #159](https://github.com/IvanLi-CN/dot-codex/pull/159). Direct VM use and isolated lifecycle/reclamation observations are recorded in the implementation companion; formal review and delivery state belong to the live candidate evidence. Native preflight exposed and corrected the raw Incus query project-flag incompatibility.
+- Actual VM use corrected native agent-readiness waiting, older-Python source hashing and restart-required disk visibility. A real interruption before expiry-timer creation exposed a missing-unit reconciliation defect; exact native absence proof now allows recovery without manually rebuilding a timer. The corrected source was installed and the affected recovery/expiry scenarios rerun.
+- Native NAT preflight found the restricted `agents` project had no explicit proxy-device allowance. The deployment owner changed only `restricted.devices.proxy` to `allow`; candidate control now checks that setting before allocation and refuses to proceed when it is absent or blocked.
+- Capacity admission is confined to the authorized CT filesystem. The earlier external storage probe requirement was removed from source, deployment configuration and operating instructions; no PVE storage evidence is part of acceptance.
+
+## Lifecycle / Compatibility
+
+This topic supersedes the shared host execution contract in `shared-testbox-heavy-validation`. That directory is retained for historical context and supplies no current operating entrypoint. There is no compatibility fallback.
+
+## Replacements / Background
+
+ADR 0025 replaces ADR 0015 with per-session Incus guests, explicit leases, lazy stopped-disk caching and native timer reclamation. An earlier unmerged Broker/gateway candidate was withdrawn; its source and acceptance are not inherited. The implementation starts from remote main at `7f27d636bf059de37abf61eadd8c9cf645d5048d`. The native decision uses 0025 because upstream assigned 0024 to release policy during implementation.
+
+## References
+
+- [Requirements](SPEC.md)
+- [Implementation](IMPLEMENTATION.md)
+- [Historical contract](../shared-testbox-heavy-validation/SPEC.md)

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/IMPLEMENTATION.md

@@ -0,0 +1,144 @@
+# Agent VM implementation
+
+## Current Status
+
+- Lifecycle: active.
+- Implementation: protocol 4 explicit live-memory adjustment and the 48-GiB logical RAM ceiling are installed and observed with the archived source below. Protocol 3 reclamation/count-policy and retention results below are historical baseline evidence. PR readiness remains bound to current delivery validation and review evidence.
+- CT base layer: Arch Linux, Incus resources and KVM present; this is not CLI/lifecycle acceptance.
+
+## Live memory implementation and acceptance
+
+The implementation provides explicit memory-only native live adjustment, pressure-independent reduction, guarded growth and conservative partial-failure accounting without automatic restart/stop. CPU/RAM ratios are 4/4 over unchanged 15-vCPU/12288-MiB bases, yielding 60 vCPU/49152 MiB; these are logical allocation ceilings. The daily Skill directs voluntary downsize after high-memory work when remaining workloads fit, preserving disks/cache and explicit lease renewal.
+
+Initial native 4-to-2-GiB shrink and later 12-to-4-GiB shrink attempts returned convergence timeouts despite subsequent guest memory changes. Those errors remain failed evidence. The corrected shrinking path waits once for 45 seconds before its sole guarded completion; growth/hotplug is never retried automatically. Offline tests cover partial accounting/replay, pressure and unavailable metrics, boot/lease continuity, mode/protocol rejection and expiry/drain/configuration/reservation changes during settlement.
+
+After production leases naturally ended at `2026-10-07T06:23:28Z`, the deployment owner installed the correction from `57b098ed252f7dcedfb6f8ce8237e6a89a6771ab`: control SHA256 `9d3665069a6d09d02084bfc4252f822f00fb3bd9345e4531b4661433693814f1`, CLI SHA256 `4ae8db7a9c7e4ca6fe9dfe27758fec0ceb428abc05a8f58907c65f76049eac1c`, protocol 4/version `0.4.0-native`. The earlier accepted RAM configuration change is ratio 2 to 4; the final control correction preserved that configuration, CPU/base budgets, native units, state and unrelated project settings. The parent independently checked installed source hashes. Health/default admission passed before drain exit; no runtime-home deployment or PVE access occurred.
+
+In an independent project/config/database, an idle 8-vCPU/12-GiB VM completed 12-to-4-to-12-GiB live adjustment with this control. Shrink preserved the first native timeout (`currently 11003MiB`) and a successful second acknowledgement after settlement; growth succeeded once. Conservative reservation cleared only after completion. Boot identity `496f0259-ed6a-4b89-8dd0-a5dae3e8ff0a`, QEMU PID `462650`, background services, an existing 180-second SSH, lease, port and 20-GiB disk remained unchanged. QEMU RSS fell from 1099448 to 1080452 KiB on this already lightly resident guest; that observation does not claim 8 GiB of physical memory was resident or freed. Raw positive evidence is separate from the failed predecessor and the exact isolated resources were cleaned.
+
+The same corrected control also started four low-residency VMs in a separate project/database with 4+10+10+10 GiB configured memory. Both native configuration and allocation records summed to 34816 MiB, above the CT-visible 32768 MiB and below the 49152-MiB ceiling; all four were Running and actual memory pressure was false. The parent independently inspected the archived source hash and raw doctor/native records. No large memory fill or production OOM was induced.
+
+The parent used the candidate CLI for its unique production task: acquire/reuse, source synchronization, an Alpine Docker command, live 4-to-2-to-4-GiB changes across one SSH connection, byte-exact download/online tar export, final downsize, lazy release and cache reacquisition all passed. Generation changed only on reacquisition, cached data survived and resource/lease/NAT assertions held. These observations establish actual client/guest use; document checks do not prove every future Agent follows the instruction policy.
+
+## Retention and voluntary-release instructions
+
+The candidate [daily Skill](https://github.com/IvanLi-CN/agent-toolkit/blob/main/skills/agent-vm/SKILL.md#retain-and-renew) owns the retention, explicit-renewal and closure procedure. The [shared engineering workflow](../../../skills/project-engineering-workflow/SKILL.md#step-6-post-merge) calls it at post-merge and actual task closure, while readiness handoffs use the retention policy. [REQ-AGENT-VM-009 and VER-AGENT-VM-006](SPEC.md#req-agent-vm-009--skills-and-operations) own the contract and document validation. This is an instruction change, not a new CLI/control/timer implementation or deployment. Runtime home and production VMs are untouched; document checks do not establish live model compliance.
+
+The candidate-document inspection scenarios are:
+
+| Scenario | Required instruction outcome |
+| - | - |
+| Validation ends; further VM work or build-cache reuse is likely | Retain the session VM. |
+| CI/review/owner-feedback wait, PR publication or readiness handoff with expected follow-up | Retain; report intended reuse and server deadline at handoff. |
+| Agent actively tracks the task and needs more lease time for follow-up, with no guest command running | Explicit renewal is allowed within existing limits. |
+| Drain refuses renewal, or the Agent returns control/is interrupted | No independent keepalive or continuing-renewal promise; expiry remains the fallback. |
+| PR merged with no further VM work; remote-only CI/release tracking remains | Retrieve required data, release and verify closure; continue external tracking. |
+| PR merged but VM verification remains | Finish the VM work before closure. |
+| Non-PR task completes without expected follow-up, or task is cancelled/ends further VM use | Retrieve required data, release and verify closure. |
+| Lease already ended or expired | Report observed cause and cleanup state; do not reacquire or renew for a closure claim. |
+| Release dispatch succeeds but mappings/stop are unconfirmed or cleanup fails | Report incomplete/unverified closure rather than successful release; no implicit operations authority. |
+| Release completes and the stopped cache remains | The cache is immediately reclaim-eligible; destroy still requires explicit discard authorization. |
+
+## Reclamation and instance-admission acceptance
+
+The accepted policy gives a stopped, fully cleaned, no-effective-lease cache no minimum retention period and removes the managed project's global instance-count ceiling. Manual GC selects all eligible caches regardless of age, remains dry-run by default and requires explicit application; the age timer independently retains its 24-hour selection threshold. Installed protocol 3 implements these corrections with shared object-locked eligibility, independent timer selection, count-policy preflight and default-request diagnostics. Candidate-matching installation and real acceptance pass. The detailed [reclamation design](RECLAMATION-DESIGN.md) records the settled requirements, deployment boundary and acceptance cases.
+
+Read-only inspection on 2026-10-05 observed `agents` configured with `limits.instances=8`, two running guests and six stopped caches. Durable acquisition errors explicitly record the native maximum-instance refusal. Disk headroom was sufficient, so disk-triggered reclamation did not remove caches. At that diagnosis, installed protocol 2 lacked count-policy preflight and its manual GC shared the age timer's 24-hour filter; request-triggered disk reclamation already permitted younger eligible caches. Its generic `doctor.admission_ready` did not establish that allocation ceilings had room for a new request.
+
+The observed running allocation was 12 vCPU and 24576 MiB, exhausting the accepted RAM ceiling independently of instance count. Count-limit removal must not be reported as solving RAM exhaustion. No native configuration or VM data was changed during this diagnosis.
+
+## Implementation Coverage
+
+Protocol 3 retains the protocol-2 separation of verified CT-local base budgets from multiplied allocation ceilings. Initial bases 15 vCPU/12288 MiB and ratios 4/2 yield 60 vCPU/24576 MiB. CT root cgroup metrics and verified LXCfs meminfo determine actual memory admission, without PVE or ancestor resource inspection. Stopped caches are excluded, transitions retain conservative reservations, and logical admission precedes disk reclaim or native interruption. Aggregate Incus project CPU/RAM quota conflicts are explicit errors; the deployment upgrade removes only those two keys under drain.
+
+Acquire accepts CPU/RAM/disk fields, retains omitted cached sizes and reports active-lease differences without interruption. New and cached startup verify native disk and guest filesystem sizes. Read-only observations distinguish a valid lease from a running guest and leave unexpected-stop causes unknown without attributable evidence. Pressure or invalid observations do not block existing lease operations.
+
+The offline suite covers ratio flooring, CT-only memory provenance and bounds, quota conflicts, cache accounting, atomic concurrent reservations, pre-effect rejection, pre-native rollback, expiry fencing, configurable acquire, cached age and protocol/journal compatibility. It comprises 85 client/control tests, including young-cache selection, generation races, partial deletion/reconciliation, count-policy conflicts and default-admission diagnostics, alongside the existing 12 synchronization and 4 migration tests. These fixtures are assessed separately from real deployment observations.
+
+## Protocol 3 deployment and direct observations
+
+The deployment owner installed archived source `cc029289f0e6a683e21fac4fb065faf9663f88ef` after natural drain convergence, stopped/port-free inventory and pending-operation inspection. Protected copies retain prior files, state and native settings. Control SHA256 is `8e0c9805ea53a2488fb730f636cce865ea75d48a4b0d033c0a7d7504e04ca7df`; client SHA256 is `97846f699724f7c75963f5f5de315fd018290c0441639d6e6fd8a78b52783481`; the unchanged sync helper is `ec4b0f8b2c212185fbb37755e5c55b542f07093954d74f77b886272f064b5d3e`. The parent independently verified these installed hashes and protocol 3. Project comparison contains only removal of `limits.instances: "8"`; VM/container-specific count fields remain unset. Other restrictions and the 60-vCPU/24576-MiB ceilings remain unchanged. State and journals were preserved without replay or conversion of old requests. Healthy checks preceded drain exit.
+
+The parent inspected the copied native records: nine stopped managed caches were created through acquire/release before a tenth guest was created and a cache reused. Manual GC preview retained inventory and explicit apply removed nine eligible test caches. An effective-lease guest deliberately stopped in the isolated project, a transition and an unmanaged guest survived. Age selection removed only an isolated cache marked older than 24 hours, preserving the young cache. The production clock was untouched. Exact temporary project, pool, network, profile, ACL, image and archives were removed. Production GC was preview-only; all eight production caches were preserved. No PVE access, forced interruption or runtime-home deployment occurred.
+
+The protected directory is `/var/lib/agent-vm-native/reclamation-upgrade-backup-cc029289`. Installation record SHA256 is `dc42aaf2671e18018aa57d6a246f4e8ad0122058c4367cc8872428fec909f287`; isolated record SHA256 is `8fddeba2507cededd78f208fee7fcb2c125e3da85cadcb57a976a1c74bdd0d6f`. The parent's `.tmp/agent-vm-reclamation` retains both copied records and its independent command streams. Parent observations under drain showed component health with admission refused specifically for drain; after exit, component health and default admission were both ready. Native count limits were empty and all eight caches consumed zero CPU/RAM allocation.
+
+The parent independently used its one task `avm-a533a65f2d56a116`: 2-vCPU/4096-MiB acquire resumed generation 10, identical acquire retained its deadline and task, root execution reported the requested CPU and memory, source sync succeeded, and an Alpine Compose workload ran. Download was byte-identical and stdout-only tar export was inspected as an archive. Status retained the same deadline; release yielded a port-free stopped cache, duplicate release retained its age, and reacquire reused the same task at generation 11 with retained configuration/data. Final release returned it to stopped cache. All 17 recorded commands succeeded. These observations validate the changed count/reclaim contract and daily use; earlier expiry, NAT-isolation and disk-fault records below remain explicitly historical evidence.
+
+## Protocol 2 deployment and direct observations
+
+The existing deployment conversation installed source from `8b6a376da4ccba19a56845e6c0305353d2414f1b` after drain, natural lease convergence, stopped/port-free inventory and pending-operation checks. Protected copies retain the old control, configuration, state database and native project/profile/network settings. Installed control SHA256 is `dcb5a60b5d656949972b63ae57a8ba7411bc181e0c61ddcdafd0fceb0d8f18d9`; client SHA256 is `f6855a51b4ceae708aab4198d717d4fa938b1fe487ea10cecf49011833e1bfed`. Protocol 2 preserves the existing state and operation journals. Project comparison shows only aggregate `limits.cpu` and `limits.memory` removed; other project limits, profile and network ACL remain unchanged. Healthy checks preceded normal drain exit.
+
+Observed production policy retains bases 15 vCPU/12288 MiB and ratios 4/2, with allocation ceilings 60 vCPU/24576 MiB. The verified CT view reports 16 CPUs and 24576 MiB through LXCfs; its root `memory.max` is unlimited. No PVE or ancestor metrics were consulted. Production doctor reports the separate base, ceilings, allocated/reserved totals and actual headroom; stopped caches count as zero CPU/RAM. SSH maintenance alias remains root at `192.168.31.19:22`, with host checking enabled. No resident custom service or Codex runtime-home deployment was added.
+
+Isolated acceptance used the same control source in a separate Incus project/profile/state database. Its RAM test ratio was 3, yielding a 36864-MiB test ceiling; production remained at ratio 2. Three idle guests each configured with 8 CPUs/10240 MiB started together, totaling 24 CPUs/30720 MiB above the CT-visible 16 CPUs/24576 MiB. Native limits and all three guest CPU/memory readings agreed. At the simultaneous observation, verified headroom was 22344599552 bytes against a 2576980378-byte threshold, without a memory-fill workload or OOM injection. A fourth guest was refused before creation because projected 40960 MiB exceeded 36864 MiB. Cache configuration adjustment, active resize, SSH/Docker and normal release passed. Exact isolated resources and temporary keys were removed; the protected record is `/var/lib/agent-vm-native/upgrade-backup-8b6a376d/isolated-acceptance-record.json`, SHA256 `fc0a4c97e29118937cf55a35efc7e2f60637dfea55edd379e049dc2abe3467c1`.
+
+The parent independently used its own unique task `avm-a533a65f2d56a116` through candidate CLI source and the matching installed helper. Explicit acquire restored the existing 21-GiB cache as 8 CPUs/12288 MiB; guest root reported 8 CPUs and 12246692 KiB MemTotal. Identical acquire reused generation 6 and its server deadline. Source sync, an Alpine Compose workload, byte-identical download and streamed tar export passed. Explicit restarting resize to 4 CPUs/8192 MiB succeeded, with guest 4 CPUs/8130212 KiB MemTotal and the same deadline. Duplicate release preserved cache age; omitted-parameter reacquisition retained sizes and data, advanced to generation 7, and final release returned a port-free stopped cache.
+
+Protocol-2 raw observations are retained in the parent's `.tmp/agent-vm-overcommit` evidence directory: `direct-run.json`, `direct-summary.json`, per-command streams, source hashes, deployment observations and the copied isolated record. These records distinguish production and test policy. Historical lifecycle scenarios below remain baseline evidence; this resource-policy change does not claim to rerun all earlier expiry, NAT or disk-fault experiments.
+
+## Native lifecycle baseline observations
+
+The following observations belong to the protocol-1 delivery in PR #159. They establish historical native lifecycle coverage and are not current protocol-3 deployment or empirical acceptance. In particular, the older CT memory observation and project aggregate quotas below are baseline facts rather than the new allocation policy.
+
+The command contract is archived in `contracts/cli.md`. Daily and operations responsibilities live in the public `agent-toolkit` Skills [`agent-vm`](https://github.com/IvanLi-CN/agent-toolkit/tree/main/skills/agent-vm) and [`agent-vm-ops`](https://github.com/IvanLi-CN/agent-toolkit/tree/main/skills/agent-vm-ops). Fresh control/client drafts have been imported into this candidate; subsequent corrections belong only to candidate source. The deployment owner installs archived candidate copies; full VM acceptance requires the parent's direct observations with matching installed files.
+
+The candidate implements one-shot SSH management, durable operation records, explicit generation-aware leases, native NAT, stopped-cache reclamation, conservative resource reservations and a guarded source-sync commit. Capacity admission measures only the CT-local Incus pool filesystem. External storage probes and their mandatory admission dependency have been removed; legacy probe configuration is rejected without execution. Offline fixtures verify those boundaries; they are not evidence of actual Incus behavior or deployment acceptance.
+
+Preflight exposed that Incus 7.5.1 rejects global `--project` flags on raw `query` commands. Candidate source now supplies project identity only in the API URL and tests enforce that subprocess contract. The correction is installed from `6f0d6e9a34215f1ac688bf3c36ffcef5c567d30d`; independent CT verification matches control SHA256 `6579b9e7473adf20f19c79e0c74d7bd34dd58ba9bedc4bddfd2abeaa99e0b693`. The parent task actually ran the installed CLI: `doctor` no longer reports query errors, and `status` reports absent/no effective lease. Changes to protected connection-material wording do not introduce a registration system or role credentials.
+
+The host alias independently resolves to root at `192.168.31.19:22` with strict checking. Installed client/control communicate over the existing SSH service. The deployment owner verified native units, the 15-minute calendar, the root-owned isolation ACL and absence of resident custom control processes. These preflight observations do not establish guest access, network isolation or expiry behavior.
+
+The deployment owner verified 16 CPUs in CT affinity and a project CPU limit of 16; the configured admission budget is 15, reserving one CPU for the host. CT memory visibility is 16 GiB and the project limit is 32 GiB; the configured budget is 12288 MiB, reserving 25% of the smaller capacity. The parent independently verified these configuration fields and root-owned mode 0600. The default 2-CPU/4-GiB guest fits these budgets. The CT-local correction is installed from `5efeba1c50c90cae131831396cf69106aadf304f`, control SHA256 `1616d0ac2852796d428fbc5044bed6d7ac7e401f931deca432e8b04d05d4be46`; the parent actually observed `scope: ct-filesystem` from the installed CLI. The external capacity dependency is removed.
+
+Image preparation exposed a separate preflight defect: an unavailable configured fingerprint did not prevent `doctor` from reporting ready. Candidate control now verifies exact image identity and VM type during preflight and before a fresh allocation can reclaim caches or create a VM. The guard is installed from `c62e4c0ec27e7cda647e581a30524e5b3d39c671`, control SHA256 `a6a144d119031d1db114e15e59fb4a9ee0029b7551def9432dc2f94f7fdfabee`, independently checked by the parent.
+
+The deployment owner prepared Debian 13 fingerprint `4b2ddc09353aec82c77770c3868690649351e8438252bb01823eed548f423d86`, verified required tools, Docker/Compose, network-online and SSH/Docker/containerd services, and confirmed two fresh clones have different host keys. Temporary VMs and intermediate images were cleaned within their exact owned scope. The parent actually ran installed `doctor` with that pin: `ready: true`, no issues, CT-local capacity only. Candidate defaults and the installed configuration match the verified pin.
+
+The parent's first real acquire from `88f3af2c760e91a588a3f40273c138c4d8b300b3` failed because the VM agent was not yet running. Cleanup stopped the guest and retained a port-free cache. Candidate acquisition, restart and restarting resize now use bounded native `incus wait` for agent and IPv4 readiness, capped by the current lease and followed by state/generation checks; they do not add a control-owned polling loop or extend the lease. The deployment owner installed this correction before the parent's next acquisition.
+
+That acquisition exposed the restricted project's default proxy-device prohibition. Within the native NAT deployment scope, the deployment owner changed only `agents` project `restricted.devices.proxy` to `allow`, preserving its other restrictions and quotas. Candidate preflight now checks this exact permission before admission. The parent then acquired the cached VM successfully: active generation 3, guest IP `10.250.19.20`, SSH mapping `192.168.31.19:20000`, with a server deadline of `2026-10-04T16:01:24+00:00`. This proves acquisition and mapping creation, not the remaining guest-use and expiry assertions.
+
+Installed root SSH and remote exit-status propagation are observed. The first synchronization run failed before remote mutation because the installed client's Python lacks `hashlib.file_digest`. Candidate hashing now uses standard streaming SHA256 on both sides, preserving manifest verification without a Python 3.11 dependency. The deployment owner installed helper SHA256 `ec4b0f8b2c212185fbb37755e5c55b542f07093954d74f77b886272f064b5d3e`; the parent synchronized 1495 files twice, confirming stale source removal, `.git` exclusion and adjacent result preservation.
+
+The parent also observed root native SSH, a successful Alpine 3.22 Compose workload, byte-identical upload/download and online-only tar export. TCP `20001` and UDP `20002` mappings carried actual LAN traffic; a conflicting explicit allocation was rejected and both mappings became unreachable after exact removal. Repeated acquire and these operations preserved the lease deadline. One explicit renewal added 15 minutes.
+
+Real disk growth exposed a native visibility requirement: root configuration changed from 20 to 21 GiB but the running guest still saw a 20-GiB block device. The attempt returned `resize_partial`, never success. Candidate resize now requires explicit restart allowance for any resource change, including disk growth, and returns an unapplied plan before reclaim or mutation when absent. After restart it verifies agent/network readiness and guest filesystem growth; an explicitly requested unchanged disk size also verifies or repairs growth. Partial error details remain available after stopped cleanup.
+
+The installed control from `79313f17b8f35a98f263670d90b29da7255e8172` matches SHA256 `f9596203acff2fd3a692747324f87396f26bb5290210ad8be9f46ff16e922652`. The parent verified the unapplied disk plan, then explicitly allowed restart. Resize completed in 34.209 seconds: guest block capacity `22548578304` bytes (21 GiB), ext4 capacity `21675147264` bytes, and unchanged lease deadline. The filesystem grew during restart before the helper's idempotent verification. Reservations and the partial error cleared after verified completion.
+
+Lazy release completed in 1.352 seconds; an existing SSH with one-second keepalive detection exited after 1.353 seconds. New connections were rejected and mappings were empty. Duplicate release preserved `inactive_since`. Reacquisition reused the same instance with generation 4, restored SSH alone and retained the test result; the parent released it again at server time `2026-10-04T16:09:47+00:00`. It is a stopped cache, not an active lease. These release observations do not replace short-lease expiry and ControlMaster acceptance.
+
+The deployment owner exercised the unchanged installed control in an isolated project and pool, and the parent inspected the resulting raw records. Positive CT-to-guest TCP/UDP traffic, laptop-to-mapped-SSH traffic, guest DNS and an Alpine pull succeeded. Peer-to-peer access to the same positively tested listener, reflection through the CT's LAN address, and access to bridge management SSH failed as intended. The parent retained `network-positive-negative.json` in its external evidence set; the earlier incomplete harness is preserved separately and is not counted as a pass.
+
+The production-equivalent isolated expiry timer used the persisted absolute lease deadline, `Persistent=yes`, one-second accuracy, zero randomized delay and a task/generation token. The parent inspected `expiry-evidence-oncalendar-2.json`: at the `2026-10-04T17:18:14Z` deadline, native proxy removal and exact conntrack clearance were observed within 1.010 seconds, and Incus STOPPED/cache state within 1.543 seconds. Matching established flows existed before expiry; no global conntrack flush was used. An independent laptop LAN observer received an SSH banner before expiry and could not complete connections afterward. New SSH and late renewal were rejected. Earlier relative-timer results are auxiliary evidence only.
+
+Client detection is distinct from server withdrawal. A default ControlMaster and long SSH did not exit naturally within their 20-second observation windows, and the raw LAN holder did not receive EOF within its bound; those latencies remain lower bounds, not successful fast-disconnect measurements. The server entry-withdrawal and stop targets were measured directly. Client keepalive settings were not changed to improve the expiry result.
+
+An old generation-1 timer left generation 2 active. In the separate same-generation experiment, explicit renewal moved the deadline from `17:32:45Z` to `17:32:55Z`; the timer arriving after the former deadline returned `rearmed/not-expired`, and actual Incus Running state and its exact NAT mapping remained intact. `renew-timer-same-generation-3.json` contains the worker results and native observations. Earlier invalid-generation, scheduling and test-unit cleanup attempts are retained without being treated as passing evidence. Exact proxy-removal fault injection also produced `cleanup_incomplete`, still stopped the guest and retained port/error records; applied reconciliation then reached a port-free cache without resetting its age.
+
+The isolated control process was then actually SIGKILLed after its preparing record and reservation were durable, with the VM Running and its SSH proxy present. Applied `boot: true` reconciliation withdrew the proxy and port records, stopped the VM and cleared reservations while preserving all original ownership metadata. The parent inspected `process-interruption-boot-evidence-2.json`; exact destruction subsequently left an empty test inventory. No CT reboot was performed. Some supplemental harnesses recorded `finished_at` before dispatch, so those fields are not command-duration evidence; state assertions and independent native expiry observations are assessed separately.
+
+A second real interruption, immediately after durable reservation and before timer creation, exposed a recovery defect: native disable rejected the nonexistent timer and left the task closing with reservations held. `recovery-missing-unit-evidence.json` preserves the failure before exact test-only cleanup. Timer removal now accepts this case only after native `not-found/inactive` state, empty fragment/unit-file properties and absence of the exact file are verified. Loaded/active units, existing files and unavailable inspection still preserve the original failure. The correction is installed from `47a33987bcc43b66aff251112e9fa193ff0d9724`, control SHA256 `7c581c9149d1ed038d1e3a399aeb34d7e6b63ca75608598512baf95d2a1c19cd`, independently checked by the parent. Real pre-timer SIGKILL followed by boot reconciliation now reaches absent with no ports, reservations, native instance or manually created timer.
+
+The corrected control also passed an absolute-timer rerun after a `PrivateTmp=yes` visibility preflight for its isolated configuration/state. At the `18:27:00Z` deadline, mapping removal and connection refusal were observed at 1.263 seconds, then native Stopped/cache state at 1.823 seconds. The timer service succeeded, late renewal was rejected and exact destruction succeeded. `expiry-oncalendar-fixed-4.json` retains the raw observations; earlier invisible-helper/config attempts are invalid harness runs and are not counted. The control change is confined to the missing-unit error path; the inspected unchanged lifecycle, network and reclaim paths retain their earlier scenario evidence.
+
+Real reclamation observations include stable release age, old-only 24-hour GC, oldest-first pressure reclaim and refusal after insufficient reclaim. Two stopped 20-GiB guests occupied `1651384320` and `1651380224` bytes in their exact CT-local VM directories. A new admission reclaimed only the older cache and preserved the newer directory; a deliberately unreachable test watermark then rejected creation after eligible reclaim. Effective leases, transitional records and an actual stopped unmanaged VM survived their protection scenarios. During real 21-GiB resize, the target's durable reservation remained protected and cleared only after native/guest capacity verification. All test watermarks, ages and costs belonged to isolated configuration/state; production clock, lease defaults and filesystem capacity were not altered.
+
+Drain rejected new acquisition and renewal while preserving an existing lease and allowing release; exit restored admission. An unavailable CT-local capacity observation rejected acquisition with no new instance. The parent separately generated real ENOSPC by writing 2 MiB into a 1-MiB guest tmpfs: the installed CLI preserved exit code 1 and the diagnostic, removed that exact mount/directory and preserved the lease. The parent then synchronized the corrected source, verified its guest hash and released generation 5 in 1.368 seconds; the mapped port closed and duplicate release preserved age. This guest filesystem fault is not evidence that the CT filesystem was filled.
+
+The deployment owner cleaned every exact isolated project/pool/network/profile/image/ACL, test unit and temporary directory. The parent inspected the copied raw records and final installed file modes/hashes. Native Incus and the age timer remain healthy; there is no deployed custom resident listener. Independent final inspection found three retained historical systemd slices active with `TasksCurrent=0`: these are empty metadata, not running test services. The parent cache remains stopped. SSH resolves to root at `192.168.31.19:22`; observed CT packages are Incus `7.5.1-1`, systemd `262-1`, OpenSSH `10.5p1-1` and conntrack-tools `1.4.9-1`, with no entries from `pacman -Qu`.
+
+Offline validation passes: 44 client/control tests, 12 synchronization tests, 4 migration tests, fixed context checks (145 tests and Skill index), Skill format checks, migration scanning and Spec/document checks. Capacity tests verify CT-only measurement without command execution, rejection of removed probe configuration, invalid/unavailable local metrics and protected reclamation. Image-guard tests reject missing or non-VM images before allocation or cache reclamation. Native readiness tests check ordering, stopped cleanup after failure and expiry without implicit renewal; the project-permission test rejects a proxy prohibition before allocation. The synchronization suite verifies binary transfer and commit without the newer hashlib API. Resize tests model stale running-guest disk capacity and verify recovery after stopped cleanup and a new lease. Native timer-boundary tests cover the uncreated-unit recovery case and fail-closed behavior for conflicting or unverified state.
+
+## Evidence Boundaries
+
+- Host reboot behavior was exercised through the real boot-reconciliation action after controlled process interruptions; the CT was not rebooted.
+- Client disconnect detection has only the separately recorded bounds above. There is no expiry recovery promise and no claim of ENOSPC prevention under overselling.
+- Raw evidence is retained outside the source tree, including `/tmp/g6-20261005-evidence`, corrected recovery/expiry records and the parent's direct-use evidence set. Failed harnesses remain distinguishable from passing scenarios. Delivery readiness and formal review are tracked against the live PR, rather than inferred from these implementation observations.
+- No PVE storage information is required or authorized; only the CT-local filesystem is part of admission and acceptance.
+
+## References
+
+- [Requirements](SPEC.md)
+- [History](HISTORY.md)

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/RECLAMATION-DESIGN.md

@@ -0,0 +1,72 @@
+# Agent VM cache reclamation and instance admission
+
+This accepted design concerns the existing CT109 native Incus implementation. Its requirements and manual-GC selection policy are settled; no deployment or implementation completion is implied.
+
+## Requirements and decisions
+
+- Each session keeps at most one managed VM, including its transition and cached states.
+- An effective lease remains protected. An unexpectedly stopped guest with an effective lease is not a reclaimable cache.
+- Expiry or release ends access and stops the guest. Once native access cleanup and stop are confirmed, its managed cache is immediately eligible for reclamation. There is no minimum retention time or promise of recovery.
+- Eligibility does not require immediate deletion. Release retains a disposable cache for possible reuse; requests reclaim eligible caches only when needed. The native 15-minute age sweep selects caches idle for at least 24 hours, which is a cleanup trigger rather than a retention guarantee.
+- Manual `admin gc` selects all eligible stopped caches regardless of age, with dry-run as the default and explicit application required for deletion. Its selection policy is separate from the age timer.
+- Remove the `agents` project's global instance-count ceiling. Do not replace the eight-instance limit with another arbitrary instance-count limit or introduce instance-slot reclamation machinery.
+- Keep the accepted CPU/RAM allocation ceilings, CT memory-pressure admission, disk admission, per-VM resource limits and unrelated native restrictions. Stopped caches consume no CPU/RAM allocation budget but retain real disk occupancy.
+- No new resident service, polling loop, automatic renewal, PVE access or forced interruption of another effective lease is authorized by this design.
+
+## Observed failure
+
+Read-only observations on 2026-10-05 found `limits.instances=8`, eight native instances (two running and six stopped caches), and durable failures containing `Reached maximum number of instances in project "agents"`. Disk reclamation returned without deleting caches when disk headroom was sufficient; native creation then hit the independent count ceiling.
+
+At that observation the two running guests also consumed all 24576 MiB of the accepted RAM allocation ceiling. Removing the count ceiling does not make memory admission unlimited or guarantee that another creation will succeed.
+
+At diagnosis, installed protocol 2 had no instance-limit policy check. Its manual `admin gc` and age timer shared the same 24-hour selection filter. Its `doctor.admission_ready` did not check exhausted allocation totals or instance-count configuration, so a true value is not a promise that a new VM fits.
+
+## Design
+
+### Native admission
+
+An explicitly authorized deployment removes only `limits.instances` from `agents`, preserving other project/profile restrictions and all state. The operation neither deletes caches nor stops guests. Do not enlarge CPU/RAM ceilings as a side effect.
+
+Doctor and mutating admission inspect native project configuration. A finite instance-count ceiling conflicting with the accepted policy produces a structured configuration error before any reservation, reclamation, port allocation or guest mutation. Daily requests never silently change the native project. Check both general and VM-specific count restrictions if exposed by the installed Incus version; validate native configuration keys before relying on them.
+
+An absent count ceiling is policy compliance, not evidence of capacity. Admission continues to reserve CPU/RAM atomically, evaluate actual CT pressure, reclaim disk only if needed, reserve native resources, and create or restore the guest. Cached restoration does not acquire an additional session slot. Disk reclamation remains oldest-first and stops when its existing capacity policy is satisfied.
+
+### Cleanup selection and execution
+
+Separate eligibility from selection. A shared eligibility check requires the current managed identity, stopped cache state, no effective deadline, stopped native guest and no remaining managed mappings. Unknown, transitional and effective-lease objects remain excluded regardless of native power state or elapsed time.
+
+Selection has three callers:
+
+| Caller | Selection | Minimum age |
+| - | - | - |
+| Request-triggered disk reclaim | Oldest eligible caches until sufficient capacity | None |
+| Native age timer | Eligible caches at or beyond the configured idle threshold | 24 hours by default |
+| Manual `admin gc` | All eligible stopped caches; dry-run unless explicitly applied | None |
+
+Manual GC remains dry-run by default. Applying cleanup reacquires each object's lock and rechecks current eligibility and generation before deletion; a cache resumed after the preview must survive. Do not hold the global lock while waiting for native deletion. Confirm disappearance before clearing durable ownership. Failed deletion retains an accurate transitional/error record for bounded reconciliation; it must not report successful capacity release.
+
+The age timer must explicitly select age-based cleanup rather than inherit manual defaults. Duplicate release, retries and queries do not restart cache age. An expired active object still in access cleanup is not deletable until that cleanup is confirmed.
+
+### Diagnostics and protocol
+
+Keep component health distinct from policy compliance and request admission. Expose native instance inventory and count restrictions, running versus stopped-cache totals, allocation remaining and concrete blocking reasons. Describe any aggregate readiness field precisely: a generic healthy flag is not approval for an arbitrary resource request. Admission errors retain requested sizes, projected allocation and actual remaining capacity.
+
+Do not infer OOM from a stopped guest or shared CT counters. Do not hide a resource denial behind the removed count ceiling. The broader manual-GC selection requires a versioned CLI/control contract so an old client cannot silently request a broader destructive operation; preserve existing state, lease generations and operation journals rather than resetting or rewriting them. Requests recorded under the old protocol must not be rewritten or automatically replayed under the new semantics.
+
+### Documentation and rollout
+
+Update the existing Spec, CLI contract, both Skills, deployment reference and implementation coverage to distinguish reclaim eligibility, selection and completed deletion. Keep the canonical glossary free of implementation instructions. The existing native-lifecycle ADR owns the no-retention-guarantee boundary; this correction does not need a new architecture or backend.
+
+When implementation is separately authorized, the candidate worktree remains the sole source writer. The existing deployment conversation installs matching archived versions and reports exact native project differences and checksums. Existing maintenance/drain rules govern an executable or protocol upgrade. A configuration-only removal must not be described as a VM cleanup or a CPU/RAM policy change.
+
+## Acceptance
+
+1. More than eight native instances, including stopped caches, do not fail solely because of an eight-instance ceiling; per-session uniqueness and normal resource admission still apply.
+2. A just-ended, fully stopped and cleaned cache is eligible immediately. A guest stopped unexpectedly during an effective lease is protected.
+3. Disk sufficiency does not cause needless cache deletion. Disk pressure can reclaim a young eligible cache, oldest-first, stopping when enough capacity exists.
+4. Manual GC preview includes eligible caches younger than 24 hours and deletes nothing. Explicit application can delete those caches after fresh eligibility checks; the age timer independently selects only caches at least 24 hours old.
+5. Concurrent resume or renewal defeats stale cleanup intent; deletion failures and interrupted access cleanup remain accurately reported and do not release ownership early.
+6. Native configuration conflicts and exhausted RAM allocation produce distinct diagnostics. Component health cannot be mistaken for approval of a new request.
+7. Versioned destructive semantics reject incompatible peers while preserving database and journal history. No resident custom process, PVE probe or unrelated resource mutation is introduced.
+
+Real observations use precisely owned temporary sessions and isolated configuration. Do not fill production memory or disks, stop other effective leases, reset server time or flush conntrack globally.

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/RETENTION-DESIGN.md

@@ -0,0 +1,17 @@
+# Agent VM retention and voluntary release
+
+This accepted design explains why Agent VM retention follows expected task continuation rather than individual validation phases. [REQ-AGENT-VM-009](SPEC.md#req-agent-vm-009--skills-and-operations) is the normative contract; [CONTEXT](../../../CONTEXT.md#agent-vm) owns the domain terms. This document is design background, not another operating entrypoint.
+
+## Retention and closure boundary
+
+Releasing after every validation would turn build-cache reuse into a race with global reclamation and repeat expensive setup during one continuing task. The accepted boundary is actual task closure: PR merge without further VM work, completion of non-PR work without expected follow-up, cancellation or a confirmed end to VM use. Readiness handoffs and ordinary waits do not establish that boundary by themselves.
+
+An expected continuation is a reason to retain an effective lease, not an independent retention guarantee. An actively progressing Agent may explicitly renew for that use; execution interruption or returning control does not provide ongoing renewal. Expiry remains the fallback. The existing native lease and disposable stopped-cache semantics are unchanged.
+
+## Responsibility and evidence
+
+[agent-vm](https://github.com/IvanLi-CN/agent-toolkit/blob/main/skills/agent-vm/SKILL.md#retain-and-renew) owns the retention, renewal and Finish procedure. [project-engineering-workflow](../../../skills/project-engineering-workflow/SKILL.md#step-6-post-merge) invokes it at the relevant phase and closure points. This keeps one operating policy while preserving the engineering flow's independent review, CI and publication duties.
+
+[Implementation coverage](IMPLEMENTATION.md#retention-and-voluntary-release-instructions) records candidate-document scenarios separately from native deployment and live-model evidence. Closure is established by observed lease/access/guest state; a command dispatch or prior expiry cannot substitute for that observation. Existing data-loss authorization remains unchanged.
+
+All interview decisions are confirmed. This reversible instruction-policy clarification fits the existing native lifecycle decision and does not require a new ADR, CLI/control change, timer change or deployment.

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/SPEC.md

@@ -0,0 +1,123 @@
+# Native Incus Agent VM
+
+## Context and Scope
+
+Agent code needs an isolated Linux machine with root SSH, Docker/Compose and predictable resource ownership. This topic owns the CT109 LXC + Incus VM lifecycle, its one-shot client/control contract and the two Agent Skills.
+
+The implementation consists of a Python client, a one-shot CT control command, a source synchronization helper and native systemd units. Resident custom services, gateways, HTTP APIs, implicit keepalive, shared caches, export storage, snapshots and guaranteed recovery after lease end are outside this contract.
+
+## Terms and Interfaces
+
+The canonical domain language is in [CONTEXT](../../../CONTEXT.md#agent-vm). The command surface is [the CLI contract](contracts/cli.md). `CODEX_THREAD_ID` selects resource ownership; it is not authentication. The same trusted computer has management access for daily and operations tasks. Skills and task authorization separate those responsibilities.
+
+## Requirements
+
+### REQ-AGENT-VM-001 — Execution boundary
+
+The system MUST use the existing host SSH 22 to run bounded control actions with JSON on stdin. Production custom executable entrypoints MUST be limited to the local client, CT control and synchronization helper. It MUST NOT add a resident Broker, gateway, API, poll loop, extra host sshd or automatic keepalive. Diagnostics MUST go to stderr and be forwarded in real time by the client; management output MUST remain JSON with protocol identity, server time and actual state. Missing session identity or incompatible protocol MUST fail clearly. Acquire, restart and restart-capable resize management requests MUST allow 600 seconds of local transport time; other management requests retain 240 seconds. A transport timeout or unknown result MUST identify the operation ID without re-requesting the mutation.
+
+### REQ-AGENT-VM-002 — Ownership and idempotence
+
+Each session MUST occupy at most one VM slot, including preparing, closing, deleting and cached states. Mutations MUST use operation identity, lease generation, atomic durable records and coordinated short global/object locks. Retried requests MUST NOT duplicate a lease extension, VM or port. Startup, stop and deletion waits MUST NOT hold the global lock. After native start completes, agent and IPv4 readiness MUST share one monotonic-clock 300-second budget; a normal readiness timeout MAY continue one bounded native wait using the remaining budget, while explicit native failure or a stopped guest MUST fail promptly. Each native wait transport timeout MUST be no greater than its integer remaining budget, and bounded diagnostic sources MUST charge their time against the same deadline. At 120 seconds without readiness, control MUST emit one bounded slow-start diagnosis and continue the same startup without restarting it. Lease expiry or generation change MUST reject late readiness and commit results, and a stale late result MUST NOT reopen NAT. Credentials MUST remain outside source, argv contents and ordinary logs.
+
+### REQ-AGENT-VM-003 — Explicit leases
+
+The default guest MUST be Debian 13 with 2 vCPU, 4 GiB RAM and a 20 GiB virtual disk. Acquire MUST accept explicit CPU, memory and disk requests. Omitted fields MUST use defaults for a new guest and retain verified sizes for a stopped cache. A differing explicit request on an effective lease MUST report the mismatch and require explicit resize rather than interrupting the guest. Initial leases MUST last 30 minutes; each explicit renewal MUST add 15 minutes up to a remaining window of two hours. Repeated acquire, queries, SSH, execution and transfers MUST NOT renew. Renewal at or after expiry MUST fail. A new lease MUST have a new generation; reuse of a stopped cache MUST NOT promise recovery and MUST restore only automatic SSH.
+
+### REQ-AGENT-VM-004 — Access and native NAT
+
+SSH MUST use guest root and trusted host-key verification through native Incus proxy NAT, bound only to `192.168.31.19`. The Incus project MUST explicitly allow managed proxy devices (`restricted.devices.proxy=allow`); admission MUST fail closed when that setting is absent or different. Project ports MUST support TCP/UDP, automatic allocation and explicit free ports in the configured pool (initially 20000–29999). Allocation MUST inspect listening sockets, Incus proxies, network forwards, reservations and ephemeral ranges. The guest MUST have a fixed private IP and verified network isolation. Renewal MUST preserve mappings. Removing a mapping MUST remove its exact conntrack flows. SSH configuration MUST contain the leased port, identity and trusted host-key material; it MUST NOT disable checking or use a gateway/ProxyJump. Guest SSH filesystem access MUST NOT be constrained by the helper's workspace boundary.
+
+### REQ-AGENT-VM-005 — Expiry and lazy release
+
+Persistent native timers MUST recheck the current generation and deadline. Expiry or release MUST remove all managed NAT mappings, delete only their precise conntrack flows and force-stop the VM, continuing stop attempts after cleanup errors. A slot or port MUST NOT be freed before cleanup is confirmed. Failures MUST retain a non-active transitional record for bounded retry. VMs MUST be non-ephemeral with autostart disabled; boot reconciliation MUST fail closed. Under normal load, access revocation MUST complete within two seconds and VM stop within ten seconds; client disconnect detection MUST be measured separately.
+
+### REQ-AGENT-VM-006 — Cache reclamation
+
+Release MUST normally retain a stopped disk as a disposable cache, without a minimum retention period. Once a managed cache has no effective lease and native stop and access cleanup are confirmed, it MUST be eligible for reclamation regardless of age. Eligibility MUST NOT imply immediate deletion. Cache age MUST start at the most recent lease end, including early release, and MUST NOT change on duplicate release, status or retry. A native 15-minute age sweep MUST reclaim managed stopped caches idle for at least 24 hours; this threshold MUST NOT be treated as a retention guarantee or an eligibility floor for other cleanup callers. Allocation, restore or resize under capacity pressure MAY reclaim any session's eligible stopped expired cache, oldest first and only until sufficient capacity exists. The system MUST NOT reclaim a valid lease, transitional object, current resize target or unknown resource, and MUST NOT run periodic pressure reclamation of young caches. Explicit destroy MUST require task authorization to discard that VM.
+
+Manual garbage collection MUST select all eligible stopped caches without a minimum idle age and MUST be dry-run by default. Deletion MUST require explicit application and a fresh object-locked eligibility check, protecting any cache that resumed after preview. The age timer MUST select age-based cleanup explicitly rather than inherit manual selection defaults. Broader destructive selection MUST use matching versioned CLI/control semantics; old-protocol requests MUST NOT be silently widened, rewritten or replayed under the new semantics. Existing state, lease generations and operation records MUST be preserved.
+
+### REQ-AGENT-VM-007 — Capacity and resizing
+
+Sparse dir disks MAY be oversold using actual allocation, request cost and reachable watermarks: initial low `max(10 GiB, 15%)`, target `max(20 GiB, 25%)`, plus request cost. Admission MUST measure only the authorized CT-local filesystem containing the Incus dir pool. It MUST NOT query PVE backing capacity, discover its storage topology or execute external storage probes. Unavailable or invalid CT-local metrics MUST reject new admission with the missing metric named. Capacity pressure MUST NOT stop a valid lease; insufficient capacity after reclaim MUST reject the new request. Actual ENOSPC/I/O errors MUST be reported. Resize MUST name a resource, MUST NOT renew, and MUST only grow disk. Memory-only resize MAY explicitly use native Incus live balloon/hotplug with no automatic restart fallback. It MUST require a running owned guest, unchanged boot identity and successful native live-update acknowledgement before committing lower accounting; guest MemTotal alone MUST NOT be treated as effective balloon allocation. Live growth MUST retain normal allocation and actual-pressure admission, while live reduction MUST NOT reclaim disks or alter NAT, deadlines or cache state. Only a memory reduction with the exact native balloon-convergence timeout reporting a current size still above the target MAY trigger one same-target completion attempt inside the original operation, after one fixed 45-second wait, with ownership, generation, lease window, drain, rolled-back configuration, boot continuity and the unchanged conservative reservation rechecked before and after the wait. At least 105 seconds MUST remain before waiting and 60 seconds before the final native attempt; the live request still requires three minutes initially. Growth MUST NOT use this retry because native hotplug effects may be repeated. The system MUST keep the full reservation, record both outcomes and never poll or attempt a third native update. A native configuration already equal to the target MUST NOT be accepted as evidence through a no-op retry. Unsupported, otherwise timed-out or still partially verified live updates MUST preserve conservative reservations and the original error without automatically stopping an effective lease; subsequent live requests MUST refuse uncertain reservations until explicit recovery or release. CPU/disk changes and the default resize path MUST retain the explicit restart contract. If restart is required without explicit allowance, it MUST report a plan without mutating. Virtual block capacity and guest filesystem growth MUST be verified separately for creation, cache adjustment and resize, with partial failures reported accurately.
+
+CPU and memory MUST support separate configurable overselling ratios, initially four for each, applied to verified CT-local base budgets with ceilings rounded down. The initial base budgets are 15 vCPU and 12288 MiB, yielding allocation ceilings of 60 vCPU and 49152 MiB. Stopped caches MUST consume no CPU/memory allocation budget; other occupied states and conservative reservations MUST be counted atomically. Resize MUST count its target only once using the larger of current and requested sizes. An explicit memory-only live reduction MUST keep the old allocation until native completion and guest continuity are verified; it MUST remain available under memory pressure or unavailable admission metrics because it adds no resource demand. Known allocation or memory-pressure refusals MUST precede cache deletion or guest interruption. Logical reservations MUST precede disk reclamation; failures MUST release only safely reversible reservations and retain partial native changes accurately. Incus project aggregate CPU/memory quotas that count stopped caches MUST be removed by authorized deployment; daily control MUST reject conflicting quotas rather than modifying them.
+
+Actual memory observations MUST remain inside the CT. A finite CT root cgroup memory limit MUST bound headroom derived from `memory.max - memory.current + inactive_file`, clamped to its limit. A verified LXCfs meminfo view, when present, MUST further bound capacity and available memory. An unlimited cgroup view MUST require verified LXCfs `MemTotal`/`MemAvailable`; missing or invalid metrics MUST reject new demand explicitly. Headroom below `max(1 GiB, 10% of effective visible memory capacity)` MUST refuse creation, restoration and growth without reserving the full requested virtual memory size. Queries, renewal, retrieval and release of an existing lease MUST remain available. Overselling MUST NOT promise simultaneous peak capacity or automatic balloon balancing. Unexpected native guest stops MUST be reported on observation without automatic restart; OOM MUST be attributed only from object-specific native evidence.
+
+Native VM resource changes, including disk growth, MUST use an explicitly allowed restart and otherwise return an unapplied plan before reclamation or mutation. Restart and restart-capable resize MUST require at least the shared 300-second readiness window remaining, while live memory adjustment retains its separate bounded window; insufficient time MUST produce an explicit denial without renewing. Native start, native disk/configuration changes and post-checks MUST retain their own bounded timeouts, so the readiness budget is not a total acquire guarantee. Partial changes MUST retain conservative reservations and identify the actual failure phase and confirmed cleanup result until native resource sizes and guest growth are verified. Explicitly requesting an unchanged disk size MUST still verify or complete guest filesystem growth, allowing recovery from a previously reported partial expansion. Slow-start diagnostics MUST record readiness stage timings, CT-visible CPU PSI, the target QEMU process runtime/runqueue wait, native status and a bounded redacted startup-log summary through protected audit data; native log retrieval MUST retain no more than 8192 bytes before redaction and mark truncation, and redaction MUST cover complete or truncated private-key blocks, quoted or unquoted secret assignments, bearer credentials, the conservative diagnostic payload suffix following any password-bearing `sshpass` flag, including quoting, concatenation, substitutions and continuations, and credential-bearing URLs for any URI scheme. Every diagnostic Incus query and log command MUST use a bounded subprocess path. Bounded diagnostic subprocesses MUST run in a dedicated process group and terminate/reap that group on timeout, with final liveness confirmation even after direct group signaling succeeds and a bounded member fallback when signaling fails; if group cleanup cannot be confirmed, diagnostics MUST report only its safe cleanup state without exposing raw command output. Diagnostic collection failures MUST never mask the original operation error or renew the lease. Native starts and managed proxy mutations MUST serialize with lease cleanup under a per-session native lock, and each late native effect MUST recheck its current generation and effective lease before applying. Final readiness, restart and mapping commits MUST re-read the durable task under the global lock and reject a changed generation, closing state or expired lease before recording success.
+
+The managed Incus project MUST NOT impose a global instance-count ceiling that includes stopped caches. Explicitly authorized deployment MUST remove the conflicting ceiling while preserving unrelated restrictions and per-VM limits. Daily admission MUST detect conflicting native count limits before resource reservations, reclamation or guest mutation, and MUST NOT silently modify project policy. Per-session uniqueness and CPU/RAM, actual-memory-pressure and disk admission MUST remain enforced. Removal of a count limit MUST NOT enlarge the allocation budgets or imply that a resource request fits.
+
+Read-only doctor MUST distinguish component health from default-new-request admission. Its admission advice MUST evaluate default resource sizes, allocation remaining, verified CT pressure, drain, native count policy, disk creation cost and existing reservations, reporting blocking reasons and required disk reclamation. It MUST NOT reserve or reclaim resources. Actual requests MUST independently execute their own atomic admission, and valid-lease reuse MUST NOT depend on default-new-request readiness.
+
+### REQ-AGENT-VM-008 — Code synchronization and retrieval
+
+Synchronization MUST select tracked and unignored files using a NUL list, exclude `.git`, skip deleted sources and reject submodules before remote writes. It MUST accept a safe single-segment name and write only `/workspace/worktrees/<name>/src`, verifying canonical parents, symlinks and helper ownership. It MUST stage in the same parent, lock concurrent commits, validate transfer and atomically replace only helper-owned source. Before commit, failures MUST preserve the prior source and adjacent results. A lost commit acknowledgement MUST be reported as unverified with recovery materials retained, without blind rollback. Temporary SSH configuration MUST be 0600 and removed on exit. The helper MUST NOT acquire, renew or release. Export MUST stream tar online and MUST NOT write an archive on CT or guest.
+
+### REQ-AGENT-VM-009 — Skills and operations
+
+`agent-vm` MUST route daily Linux, Docker/Compose and heavy validation and own the Agent's retention and voluntary-release procedure; `agent-vm-ops` MUST route explicitly authorized infrastructure work. Engineering flows MUST call the daily Skill's policy at actual task closure and after merge, without maintaining another copy of the operating procedure.
+
+After a large-memory phase ends, the Agent MUST explicitly reduce its own VM memory to a size adequate for expected remaining work when current/background workloads safely permit it, preserving the VM disk and build cache. It MUST inspect actual workload needs and the live-adjustment result rather than assume automatic balloon reclamation or shrink another session.
+
+The Agent MUST retain its session VM while the current task is likely to use it again, including build-cache reuse. Validation completion, CI/review/owner-feedback waits, PR publication and readiness handoffs MUST NOT alone trigger voluntary release. While actively progressing or tracking that task, the Agent MAY explicitly renew for expected follow-up use even when no guest command is running, within the existing lease limits and drain restrictions. Returning control to the owner or interruption MUST NOT imply continuing renewal. Independent background keepalive MUST NOT be introduced; expiry MUST remain the fallback rather than the normal closure procedure.
+
+Voluntary closure MUST follow PR merge when no further VM work is expected, completion of a non-PR task without expected VM follow-up, cancellation or a confirmed end to further VM use. Post-merge VM verification MUST finish before closure; remote CI/release tracking without further VM use MUST continue independently of VM release. Closure MUST retrieve required data online, finish guest work and use release, then verify ended lease, completed access cleanup and stopped/cache state. Failed cleanup or an already-expired lease MUST be reported from observed state rather than presented as successful voluntary release. The Agent MUST NOT acquire or renew merely to manufacture a closure result. A retention handoff MUST state the expected follow-up use and server deadline without promising future renewal. Release MUST preserve the existing disposable-cache semantics, and destroy MUST still require explicit discard authorization.
+
+Operations MUST provide health, drain, inventory, reconciliation and garbage collection with dry-run defaults. Planned drain MUST refuse new leases and extensions while permitting retrieval and release until existing leases end and cleanup is confirmed. Forced interruption MUST require separate explicit authorization. Images MUST include OpenSSH, Python, rsync and Docker/Compose and be pinned after validation. All active routes MUST use the new Skills while preserving explicit approval for local Docker.
+
+### REQ-AGENT-VM-010 — Source and deployment
+
+Archived candidate source MUST be the only implementation truth after draft import. Deployment MUST install that exact revision/checksums, retain the existing SSH management alias and report component versions, storage facts and inspectable validation. CT Arch packages MUST use a complete upgrade transaction. Codex runtime home, unrelated resources and revocation backups MUST remain untouched. Fault validation MUST use precisely owned VMs/isolated pools, without production clock changes, full production disks or global conntrack flushes.
+
+## Verification
+
+### VER-AGENT-VM-001
+
+- covers: `REQ-AGENT-VM-001`, `REQ-AGENT-VM-002`, `REQ-AGENT-VM-003`
+- Method: client/control black-box fixtures, crash/retry and simultaneous-request tests.
+- Pass condition: explicit failures and stable identity; only renewal changes an active deadline; stdout/stderr separation; no duplicate resources or resident custom process.
+
+### VER-AGENT-VM-002
+
+- covers: `REQ-AGENT-VM-004`, `REQ-AGENT-VM-005`
+- Method: real TCP/UDP NAT, conflict and network-isolation observations; short isolated leases with SSH/ControlMaster/background processes, stale timers and interrupted cleanup.
+- Pass condition: trusted native root SSH, precise mapping/flow withdrawal, expired access denied, cleanup latency targets and no damage to newer generations or other VMs.
+
+### VER-AGENT-VM-003
+
+- covers: `REQ-AGENT-VM-006`, `REQ-AGENT-VM-007`
+- Method: controlled time/admission fixtures, concurrent allocation tests and isolated storage, sparse allocation, oversold startup, reclaim and resize experiments.
+- Pass condition: stable cache age with no minimum retention floor, oldest eligible cross-session reclamation stops when enough; manual GC previews and explicitly applies cleanup of young eligible caches while the timer remains age-filtered; incompatible destructive semantics fail without widening old requests; active/unknown objects and concurrently resumed caches protected; stopped caches cannot exhaust a global native instance-count ceiling; conflicting count policy is reported before destructive effects; CT-only validated metrics; oversold ceilings and pressure refusals precede destructive effects; cache-free CPU/RAM accounting; disk/guest growth and native failures reported without peak-capacity or OOM-prevention claims; explicit live memory reduction succeeds under pressure without reboot, with preserved processes, mappings and deadlines and observed host-memory recovery; live growth retains admission and uncertain native results retain conservative accounting.
+
+### VER-AGENT-VM-004
+
+- covers: `REQ-AGENT-VM-008`
+- Method: Git file fixtures, SSH/rsync substitutes, concurrent and failed commits; real candidate synchronization and online retrieval.
+- Pass condition: special names preserved, path escape refused, original source/results retained on precommit failure, uncertain commit reported and temporary configs cleaned; tar exclusively streamed.
+
+### VER-AGENT-VM-005
+
+- covers: `REQ-AGENT-VM-009`, `REQ-AGENT-VM-010`
+- Method: migration/index/Skill checks, deployment revision verification and real use through the candidate Skill, plus drain and host SSH checks.
+- Pass condition: no retired active route, local Docker authorization retained, separate task responsibilities, exact source installed and no runtime-home or unrelated mutation.
+
+### VER-AGENT-VM-006
+
+- covers: `REQ-AGENT-VM-003`, `REQ-AGENT-VM-009`
+- Method: candidate instruction and engineering-flow inspection against retention/closure scenarios, Skill/Spec checks and source-delta inspection. This checks the instruction contract, not live model compliance or a new lifecycle deployment.
+- Pass condition: expected follow-up and cache reuse retain the VM across validation/readiness/wait boundaries; active task tracking permits explicit bounded renewal without background keepalive; merged/no-follow-up, completed non-PR and cancelled tasks retrieve then release; post-merge VM work delays closure while remote-only tracking continues after release; failed/expired closure is reported accurately without reacquisition or discard authority; the retention procedure adds no implicit lifecycle mutation.
+
+## Related ADRs
+
+- [Native Incus Agent VM lifecycle](../../adr/0025-native-incus-agent-vm-lifecycle.md)
+- [Agent VM CPU and memory overselling](../../adr/0026-agent-vm-cpu-memory-overselling.md)
+
+## References
+
+- [Implementation coverage](IMPLEMENTATION.md)
+- [Replacement history](HISTORY.md)
+- [Incus proxy NAT](https://linuxcontainers.org/incus/docs/main/reference/devices_proxy/)
+- [Incus live VM memory limits](https://linuxcontainers.org/incus/docs/main/reference/instance_options/#memory-limits-in-virtual-machines)