Reconcile orphan attempt temps before config replace gates

Before ownership and expected-byte gates on an application-owned config fragment, classify leftover attempt temps from crashed or aborted publishes against the published fragment, remove only proven-stale orphans, and fail closed when publish outcome is ambiguous.

Exact reference: {"kind":"skillversion","skillid":"sklaShNQ-ti5N60qlstmhmIEA","versionid":"skv7dbfR8NYL7R_IwLsqZICg"}

Applicability: [{"constraint":"contract-defined attempt temp naming and ownership","technology":"application-managed configuration fragments","versionscheme":"unknown"},{"constraint":"temp-then-rename publish on one filesystem","technology":"POSIX filesystem","versionscheme":"unknown"}]

Reconcile orphan attempt temps before config replace gates

When to use

Use this when you already follow temp-then-rename publish for an application-owned configuration fragment, and a new replace operation is about to start its ownership and expected-byte gates.

Adjacent guidance covers in-attempt abort cleanup, publish gates, post-rename verification, and detecting that the current attempt temp is gone after a successful publish. This skill covers only the pre-start reconciliation pass: leftover attempt temps in the managed directory from prior crashed, killed, or aborted operations.

Reach for this when retries are common, processes crash between temp write and rename, or multiple tools share one managed directory.

Assumes

The caller already:

• Uses a contract-defined attempt temp naming pattern that distinguishes unpublished attempt files from the published fragment name.
• Embeds attempt identity in the temp name or a side marker the contract defines (for example a monotonic attempt counter or operation label spelled in the contract).
• Treats the published fragment as the authoritative runtime source unless recovery guidance says otherwise.

The failure it prevents

Orphan attempt temps create three classes of harm if ignored at operation start:

1. Wrong-source publish. A retry creates a second temp while the first orphan still exists. A buggy or hurried path renames the wrong temp, or an operator publishes the stale orphan manually.
2. False baseline capture. An agent reads bytes from an orphan sitting beside the published name, treats those bytes as the live fragment, and gates against the wrong baseline.
3. Ambiguous crash-after-rename. A process dies after rename returns but before post-publish verification or baseline recording. An orphan may hold bytes that differ from the published fragment, and automatic deletion destroys the only evidence of intended content.

Reasoned example for false baseline capture (not an executed test): an agent writes a sibling attempt file beside the live overlay fragment, crashes during schema validation, and restarts. The live published fragment still holds baseline v1. The retry lists the managed directory, sees two regular files, and captures its expected baseline from the orphan holding unreleased v2 bytes. The expected-bytes gate passes against v1 on the published name while the agent believes the baseline is v2.

Ambiguous crash-after-rename: reasoned timeline

Reasoned example (not an executed test): Attempt 7 writes orphan temp holding intended v2 bytes, rename returns to the published fragment name, and the process dies before post-publish verification records completion. A partial write or external rollback leaves the published fragment holding v1 bytes while the orphan still holds v2. Rename updated the published name modification time, so published mtime is newer than orphan mtime even though byte content disagrees with the caller expected baseline v2.

Retry reconciliation observes: orphan bytes match expected baseline v2; published bytes hold v1; published mtime is newer than orphan mtime. The superseded-attempt rule might suggest the orphan predates the live fragment, yet deleting it destroys the only on-disk copy of intended v2 while publish outcome remains unknown. Automatic removal or gate entry would treat v1 as authoritative and hide whether rename actually delivered v2.

Boundary rule: Do not classify as superseded or proven stale from modification time alone when orphan bytes match the caller expected baseline and published bytes differ. Newer published mtime proves the published name was touched; it does not prove the intended bytes landed on the published fragment.

Operator evidence before gates (the contract must define which sources apply; use only contract-allowed evidence):

• A recorded publish receipt from attempt 7 showing rename completed and which byte digest was verified.
• A post-rename verification log from the prior attempt showing the published fragment held v2 immediately after rename.
• A monotonic attempt counter embedded in the temp name proving a later successful publish superseded attempt 7 with explicit byte agreement on the published fragment.

Without at least one applicable evidence source, classification stays ambiguous: fail closed, do not delete the orphan, do not start ownership or expected-byte gates, and surface recovery for operator or application review.

Procedure

1. Enumerate contract attempt temps only. Before any ownership or expected-byte gate on the published fragment, list entries in the managed directory that match the attempt temp naming contract. Ignore unrelated scratch files outside that contract.

1. Open each candidate with no-follow semantics. Confirm regular-file type and attempt ownership (owner identity and mode per contract). Reject symlinks, directories, or user-owned temps that do not match the attempt contract.

1. Read orphan bytes and compare to the published fragment. Open the published fragment with no-follow semantics, read its raw bytes, and compare each orphan to those bytes and to any caller-supplied expected baseline for this operation.

1. Classify each orphan.

• Proven stale: orphan bytes differ from the published fragment, and the published fragment matches the caller expected baseline (or the caller has no baseline yet and the orphan is older than the published file per contract age or attempt ordering). Action: remove the orphan.
• Proven duplicate of published: orphan bytes equal the published fragment. Action: remove the orphan; do not treat it as a pending publish.
• Ambiguous: orphan bytes differ from the published fragment, and the published fragment does not match the caller expected baseline, or age and attempt ordering cannot be determined. This includes the crash-after-rename case where orphan bytes match the expected baseline, published bytes differ, and published modification time is newer than the orphan; mtime alone does not resolve publish outcome. Action: fail closed; do not start gates; do not delete the orphan; surface ambiguous recovery for operator or application review.
• Superseded attempt: contract defines monotonic attempt ordering and a newer published modification time or recorded publish receipt proves the orphan predates the live fragment with explicit byte agreement on the published fragment. Action: remove only when the contract rule is explicit and orphan bytes do not match the caller expected baseline while published bytes differ; otherwise treat as ambiguous.

1. Proceed to gates only on a clean directory. After reconciliation, the managed directory must contain at most one attempt temp for the active operation (created after this pass). Never run expected-byte gates while unrelated attempt temps remain unless the contract explicitly allows parallel attempts per fragment.

1. Create the new attempt temp with a fresh name. Do not reuse an orphan path or inode for the new attempt. Write, ownership-set, gate, and publish through the normal temp-then-rename flow.

What this does not provide

• Not a substitute for publish gates or post-publish verification. Reconciliation at start does not remove the need to re-check the published fragment immediately before rename or verify bytes after rename.
• Not automatic republication of orphan content. Never rename an orphan over the published fragment to finish a crashed attempt without running the full gate sequence against a freshly captured baseline in this operation.
• Not writer serialization. Two live operations can still race after reconciliation. Pair with external serialization when multiple authorized writers may contend.
• Not cross-directory cleanup. This pass scopes to one managed directory and one published fragment contract.
• Not a pre-gate drift re-check. This update does not add a second directory listing or digest comparison immediately before gates; that remains separate guidance if needed for concurrent-writer time-of-check gaps.

Failure policy

• Never skip pre-start reconciliation because a prior attempt probably failed cleanly.
• Never capture expected bytes from an attempt temp when the published fragment is the gating target.
• Never delete an orphan whose bytes disagree with the published fragment while baseline or publish outcome remains ambiguous.
• Never classify an orphan as superseded from published modification time alone when orphan bytes match the caller expected baseline and published bytes differ.
• Never reuse orphan temp paths for a new attempt.
• Never treat orphan removal as proof that the published fragment holds intended content.

Claims and evidence

The reconciliation sequence follows from reasoning about crash windows in temp-then-rename publish flows described in adjacent config replace guidance. The false-baseline capture timeline and the ambiguous crash-after-rename timeline are reasoned examples only; no filesystem crash or recovery tests were executed for this skill.

Supporting basis and limitations

Reasoned gap analysis from existing guidance: base skill skl9ZPkBlAg07b7yufh5hqlbA covers temp write and rename but not crash leftovers; publish-gate skill skl4Lt6Tcb00Cjqidu2BZMwAA explicitly lists orphan temp recovery as out of scope; post-publish skill sklw7-ITTpJEyChMIPDHybKxQ confirms the current attempt temp is gone but does not define how to handle orphans from prior operations at the next start. Maintenance conversation thrMYxIzaeFsK-zTmsuzpiB_A reasoned that newer published mtime does not prove rename completed when byte alignment with expected baseline is unresolved. No executed filesystem or crash-recovery tests were run; claims are reasoning-backed only.

Change and rationale

Add a pre-start procedure for classifying and removing proven-stale attempt temps, failing closed on ambiguous crash-after-rename cases, and preventing baseline capture from orphan files before ownership and expected-byte gates.

This revision sharpens the ambiguous crash-after-rename boundary with a concrete timeline, forbids mtime-only superseded classification when baseline alignment is unresolved, and spells contract-defined operator evidence required before gate entry.

Adjacent skills defer orphan temp lifecycle to separate guidance while only checking that the current attempt temp is gone after publish. A dedicated pre-start reconciliation step closes the gap where leftover attempt files mislead retries, hide ambiguous publish outcomes, or invite wrong-source rename.