session-flow/handoff + find-handoff: resume-prompt path is rootless, so it resolves against a real-but-wrong directory when cwd is not the worked-in repo root

[kyle-sexton]

Summary

/session-flow:handoff writes the save-point file to an absolute location but emits a rootless
repo-relative path in the copy-paste resume prompt. When the resuming session's cwd is not the root
of the repository the handoff was written in, that path resolves against the wrong root. If a
.work/handoffs/ directory happens to exist under that wrong root — which it does on any machine
that has run /handoff from the home directory before — the failure presents as "the file is
missing" rather than "the path has no root", which is the most expensive shape to diagnose.

The same single-root assumption sits in /session-flow:find-handoff, the skill that exists
specifically to recover this situation, so the designated recovery path does not recover it either.

Observed occurrence

Session e67f9589-6925-4fc0-901e-41e4c0abec05, session-flow 0.17.14.

The session's cwd was C:\Users\<user> (not a git repository); all of its work was in a separate
local-only repository, D:\repos\...\claude-code-proxy. The transcript records both facts: every
cwd field in it holds either C:\Users\<user> or the session's scratchpad temp directory — the
worked-in repository never appears as a cwd.

The write went to the worked-in repo, which is reasonable (see "The write location is not the
defect"):

D:\repos\...\claude-code-proxy\.work\handoffs\20260726T234832Z-handoff-devils-advocate-applied.md

The emitted resume prompt, verbatim from the transcript's assistant text event:

`/clear`, then copy everything between the dashed lines:

──────────────────────────────────────────────────────────
Read @.work/handoffs/20260726T234832Z-handoff-devils-advocate-applied.md and continue its remaining next steps.
Prior session: e67f9589-6925-4fc0-901e-41e4c0abec05.
──────────────────────────────────────────────────────────

The fresh session started in the same cwd, C:\Users\<user>. That directory holds its own
.work/handoffs/ with 39 files matching *-handoff-*.md from unrelated sessions — so
@.work/handoffs/<file> resolved into a real, populated, wrong directory. The recovering session
reported four tool calls to recover the path (glob the wrong directory, search the home tree, grep
the prior transcript for the filename, grep it again for "file_path" to extract the absolute path);
that count is the recovering session's own report, not a figure this issue measured.

Note that the absolute root was available to the producer at write time and it did record it — inside
the handoff body: "Written against feat/logging-proxy at 5371e2d in
D:\repos\...\claude-code-proxy". Only the resume prompt, the one artifact the operator actually
carries across /clear, lost it.

The relative path is contract-specified, not a model slip

reference/save-point.md, "Emit the copy/paste resume prompt", full-path shape:

Read @<handoffs-dir>/<TS>-handoff-<topic>.md and continue its remaining next steps.
Prior session: <UUID>.

and immediately after it:

<handoffs-dir> is the path the write step actually used — the resolved
<memory_dir>/handoffs/ (default .work/handoffs/). Never emit a
default the file was not written to.

<memory_dir> is a repo-relative value by contract (memory_dir: .work in
.claude/topic-docs.yaml; default .work), so "the path the write step actually used" renders as a
rootless relative path. The guard that follows it is about the wrong axis: it prevents emitting a
memory_dir segment the write did not use, and says nothing about the root that segment hangs off.

skills/find-handoff/SKILL.md confirms this is the expected producer contract rather than a
one-off deviation, twice — in the detection ladder:

Apply the same placeholder filter as file mode … Confirm the referenced file exists on disk —
and resolve a relative directive path against the source transcript's cwd field, not the
current session's cwd: the producer emits repo-relative paths (e.g.
Read @.work/handoffs/…) …

and in Gotchas:

Relative directive paths resolve against the SOURCE transcript's cwd. The producer emits
repo-relative paths; a cross-repo recovery that checks existence from the current session's cwd
falsely reports the file missing.

So the model did what the engine specifies. The defect is that the specified output shape carries no
root anchor and nothing in the engine requires the emitted path to be resolvable from the resuming
session's cwd.

This is not only a cross-repo problem. @.work/handoffs/… also fails when the resuming session's
cwd is a subdirectory of the correct repository. Cross-repo is the worst presentation (a real-but-wrong
root that mimics a missing file), not the only trigger — a fix that special-cases cross-repo would
leave the subdirectory case broken.

Second surface: find-handoff has the same single-root assumption

Both rungs of the recovery ladder fail on this input.

Rung 1 — known-location glob. The skill's precompute is cwd-relative:

Default-location handoffs (this repo): !`ls -1t .work/handoffs/*-handoff-*.md 2>/dev/null | head -5 …`

and the ladder step filters candidates only on frontmatter and mtime:

Glob *-handoff-*.md, keep only files whose frontmatter is type: handoff, rank by mtime. A
strong, recent candidate → jump to step 4 …

Run from C:\Users\<user>, that glob returns 39 conforming type: handoff files from unrelated
repositories and the target is not among them. There is no repo-correlation check anywhere in the
rung — nothing in the text would reject a same-cwd, different-repo candidate. (Whether the model
would have short-circuited on one turns on its own read of "strong, recent"; the missing check is the
finding, not a predicted behavior.)

Rungs 2-3 — transcript scan. This rung does find the correct directive, and then discards it.
The rule quoted above resolves the relative path against the source transcript's cwd — which for
this session is C:\Users\<user> or the scratchpad temp directory, neither of which contains the
file — and the rung then requires "Confirm the referenced file exists on disk." The correct candidate
fails that existence check and is dropped. The rule written specifically to make cross-repo recovery
work is the rule that breaks recovery here, because it assumes the producer's cwd is the repo the
file was written into.

Anchoring the producer's emitted path fixes both surfaces at once: an absolute path needs no cwd
resolution, so rung 2-3's existence check succeeds without the cwd inference, and rung 1 stops
being the only path that can find a cross-root handoff.

The write location is not the defect

The write went to the repository the session was working in, which is the useful outcome — the
save-point lives with the work. Worth recording that it is nonetheless off-ladder: per the
topic-docs contract's "Resolution order", cwd C:\Users\<user> has no project root, and that branch
says interactive → ask (current directory or an explicit path); non-interactive →
${CLAUDE_PLUGIN_DATA}/topic-docs/handoffs/. The session was interactive and did neither; it
inferred the worked-in repo instead.

The gap is that the resolution order has no rung for "the session is working in a repository that is
not cwd's project root," so a correct-in-spirit write lands outside the ladder — and the render step
then has no root to render against. Deciding whether to add that rung is a separate call from
anchoring the path, and the path fix does not depend on it.

Proposed fix direction, and the tradeoff

The obvious candidate is to emit an absolute path in the resume prompt (keeping <memory_dir> as
the configured relative value for resolution, and rendering the resolved absolute path into the
directive). There is already precedent for absolute inside this engine's own contract:
reference/topic-docs.md specifies that the no-project-root fallback "lands handoffs under
${CLAUDE_PLUGIN_DATA}/topic-docs/handoffs/ with the absolute path announced prominently" — absolute
is already the answer on the one branch where relative has no anchor. This is the same condition,
reached a different way.

Two objections a reviewer will reasonably raise, and where they land:

• "No hardcoded/machine-local absolute paths." The topic-docs redaction bar ("committed evidence
  is distilled — no machine-local absolute paths") and CLAUDE.md's repo-agnostic rule both govern
  committed artifacts and plugin content. A resume prompt is neither: it is runtime output the
  operator pastes on the same machine, and the handoff file itself is gitignored memory tier. The
  handoff body already carries the absolute repo path today.
• Multi-machine / multi-checkout portability. This is the real tradeoff. An absolute path breaks
  if the handoff is resumed on a different machine, or in a different checkout of the same repo — and
  handoff's own "When to invoke" lists "Sharing state with another session or machine". A relative
  path is portable if the resuming session's cwd is the repo root, which is exactly the condition
  that failed here.

Shapes worth weighing rather than one asserted answer:

1. Absolute path in the directive (simplest; loses cross-machine portability).
2. Both — absolute directive plus the repo-relative path and repository identity as a stated line
   below it, so a different-machine resume has what it needs to re-resolve.
3. Keep relative but make the root explicit and machine-independent (e.g. name the repository /
   remote / checkout the path is relative to, so a mismatch surfaces as a wrong root rather than a
   missing file).

Whichever shape is chosen, find-handoff's detection contract moves with it — save-point.md
already states that changing the prompt format is a knowing break of that contract — and rung 1's
missing repo-correlation check should be closed in the same change.

Reproduction

1. Start a session whose cwd is a directory that is not the repository the work happens in, and
   which itself contains a .work/handoffs/ directory (a home directory that has run /handoff
   before is the common case).
2. Do work in a different repository and run /session-flow:handoff.
3. Observe: the file is written under <worked-in-repo>/.work/handoffs/, and the rails prompt reads
   Read @.work/handoffs/<TS>-handoff-<topic>.md.
4. /clear and paste. The @-reference resolves under cwd, into the unrelated .work/handoffs/, and
   the file is reported missing.
5. Run /session-flow:find-handoff. Rung 1's glob returns the unrelated handoffs; rungs 2-3 locate
   the correct directive and then discard it on the existence check.

Version verified

session-flow 0.17.14. reference/save-point.md, reference/topic-docs.md, and
skills/find-handoff/SKILL.md in the installed cache
(.claude/plugins/cache/melodic-software/session-flow/0.17.14/) are byte-identical to the versions on
main at fdb4dff, so the lines quoted above are the lines that ran.

Related

• bug(source-control/babysit-prs): readiness gate resolves repo from CWD, silently scores wrong PR cross-repo #1086 (bug(source-control/babysit-prs): readiness gate resolves repo from CWD, silently scores wrong PR cross-repo) — same class, different surface: a skill resolving a repository from cwd when
  cwd is not the repository in play. Not a duplicate.
• session-flow: retro context snippet assigns literal HANDOFF_DIR=.work/handoffs, bypassing memory_dir resolution if copied as-is #420 (closed) touched a nearby symptom (a literal .work/handoffs bypassing memory_dir
  resolution in a retro snippet) but is about the memory_dir segment, not the root it hangs off.

[kyle-sexton]

Correcting the version attribution in the body above, and adding two related findings from a follow-up pass. The verdict and every quoted line are unchanged.

The producing session read the engine from 0.17.4, not 0.17.14. The body states 0.17.14 was in play because that is the newest installed version. The transcript is more specific — the only session-flow files it read are:

C:/Users/<user>/.claude/plugins/cache/melodic-software/session-flow/0.17.4/reference/save-point.md
C:/Users/<user>/.claude/plugins/cache/melodic-software/session-flow/0.17.4/reference/structure.md

This does not weaken the finding. The load-bearing lines are present verbatim in 0.17.4 too — reference/save-point.md:97 carries the same Read @<handoffs-dir>/<TS>-handoff-<topic>.md directive shape, and :102-104 carries the same "<handoffs-dir> is the path the write step actually used … Never emit a default the file was not written to." find-handoff/SKILL.md:115 and :230 carry the same "the producer emits repo-relative paths" text. So the defect is present in both versions and was not introduced or fixed between them; the correction is to which copy actually ran.

The session never read the destination-resolution binding at all. reference/topic-docs.md — the document save-point.md points at for destination resolution — does not appear in the transcript, and there is no fetch of the contract URL either. The destination was resolved by inference, not by walking the binding. That is now filed separately as #1677.

The contract README is not bundled in the installed plugin. The only topic-docs file in the installed cache is the binding; the contract itself is reached by raw URL. So "apply its 'Resolution order' … as written" requires a fetch that did not happen here. Adjacent to #432, and relevant to #1677 rather than to this issue's fix.

[kyle-sexton]

This was generated by AI (triage lane, gate-audit pass — cycle 2 retry, instance melo-lap-001-triage-20260727T125559Z).

Verdict: REAL, actionable, and the only agent-ready item in this batch

The strongest-evidenced item here. It is not a model slip report — the defect is traced to contract text (reference/save-point.md, the "Emit the copy/paste resume prompt" shape plus the <handoffs-dir> note), and the body correctly identifies that the guard following that text constrains the wrong axis: it prevents emitting a memory_dir segment the write did not use, and says nothing about the root that segment hangs off. find-handoff/SKILL.md independently confirms the producer contract emits repo-relative paths, which is why the designated recovery path does not recover it either.

The follow-up comment was reviewed and does not disturb the gate: it corrects the version attribution (0.17.4, not 0.17.14) while confirming the load-bearing lines are present verbatim in both versions, and it routes its two new findings to #1677 with the explicit note that they are "relevant to #1677 rather than to this issue's fix." So this item's own scope stayed unchanged.

agent-ready because the fix is fully specified with no open judgment call: emit a rooted path in the resume prompt, and align find-handoff's detection ladder to the same assumption. No security surface, nothing irreversible, no dependency pin. The blast radius is two documentation/contract surfaces in one plugin.

Priority high: the failure presents as "the file is missing" rather than "the path has no root," which the body correctly calls the most expensive shape to diagnose, and the recovery skill built for exactly this case inherits the same assumption.

Labels applied: priority: high, work-class: scoped, agent-ready (removed priority: needs-triage).

[kyle-sexton]

[kyle-sexton]

Escalated to the human floor by lane instance MELO-LAP-001-worker-202607290351. Partial escalation — the rest of this item is shipping.

The decision that remains

Closing rung 1's repo-correlation check, which this issue requires at line 176 ("rung 1's missing repo-correlation check should be closed in the same change") and identifies at line 111 ("There is no repo-correlation check anywhere in the rung"), needs durable repo identity stored in the handoff file — a new repo_root frontmatter field in reference/structure.md.

That is a cross-cutting schema invention: every future handoff carries the field, and every consumer must tolerate its absence across the entire corpus already on disk. This lane's floor sends that to a human rather than settling it inside a fix.

The question for the operator: approve adding a repo_root frontmatter field to the handoff format (and if so, does it want its own item, or an amendment to this one), or reject it and accept that rung-1 repo correlation stays open.

Why no weaker substitute was taken

The working agent proposed and then rejected one on evidence: reuse the producer-transcript lookup rung 1 already performs and read the repository off the recovered directive.

• It makes correlation depend on a transcript that may be absent, while find-handoff's own Gotchas state transcripts are the reliable index precisely because the filesystem is not — building the new check on the weaker leg.
• For every rootless legacy handoff — the entire existing corpus — the directive yields no root, so correlation returns unvalidated exactly where rung 1 is most likely to surface a candidate. Inert where it matters, working only on files whose absolute directive could have been followed directly.

Smuggling that substitute in would have produced a check that looks closed and is not.

What ships without this decision

An open PR against this issue delivers the rest, and none of it needs a schema change:

• the absolute directive in the resume prompt
• a machine-independent re-resolution line inside the rails (repository named as prompt text computed at emit time — not a stored field)
• the detection contract accepting both rooted and rootless directive forms
• a rootless miss surfaced as UNRESOLVED rather than discarded — this is the actual reported failure; discarding it is what made the ladder useless

The PR body states plainly that it does not fully satisfy line 176.

Label note

The needs-human role label was deliberately not applied. This item has an inbound close-linked PR delivering the majority of its scope, and pulling it out of the autonomous-eligible pool mid-flight would strand that work. This marker comment carries the escalation instead. If the operator prefers the label, apply it after the PR is resolved.

Correction on record

This lane initially barred the repo_root field as out of scope. That was wrong — the working agent quoted line 176 and demonstrated the criterion exists. The split stands for a different and better reason: the work is in scope, but the schema decision is above this lane's floor.

[kyle-sexton]

This is an automated hygiene comment from an AI agent (autonomous triage lane, instance MELO-LAP-001-triage-20260729T123842Z). No labels were changed — the tradeoff below is a human call.

Marker-hygiene pass: the escalation here is live but unreachable

This item was queued for a stale-marker correction on the assumption its escalation marker was leftover noise. Verified against live state — the marker is not stale. It is current, it asks a real question, and no operator view can see it.

What was verified (2026-07-29T13:29Z)

• The <!-- work-items:escalation lane=work-loop kind=escalated --> comment (2026-07-29T07:40:56Z) states "Escalated to the human floor by lane instance MELO-LAP-001-worker-202607290351. Partial escalation — the rest of this item is shipping," and names a specific open decision (durable repo identity — a repo_root frontmatter field — needed to close rung 1's repo-correlation check).
• Current labels: priority: high, agent-ready, work-class: scoped. No human-gated role label.

Why that combination is a defect

Per plugins/work-items/skills/attend-queue/SKILL.md, an [escalated] row requires both conditions:

open items carrying the human-gated role label ... that also carry a machine-marked escalation comment whose first line starts with <!-- work-items:escalation — the marker is what discriminates a worker-escalated item from an operator-parked one; both wear the same role label, so the label alone never qualifies a row.

This item satisfies the marker half and fails the label half, so it lists in neither view: not [escalated] (no gate label), and its open question is not visible anywhere an operator looks. The decision the worker lane escalated cannot currently be answered by the lane designed to answer it. This is the mirror image of the failure work-loop's admission gate warns about for ratification markers — "an unratified item stripped of that label is invisible to the operator and can never be ratified."

The genuine tension (why this pass did not just flip the label)

The marker says partial escalation: part of this item is shipping autonomously, part needs a decision. Adding the human-gated label would surface the question but pull the shipping remainder off the autonomous frontier. That is a real tradeoff, not a mechanical fix, so it stays with a human.

Secondary finding: the work-item-lease (acquired 06:47:16Z, renewed 07:28:38Z, ttl_hours: 2) expired around 09:28Z and was never released. It is stale and safe to reclaim.

Options

• RECOMMENDED — split the escalated decision into its own item. File the repo_root / repo-correlation decision as a separate needs-human issue linked to this one, and leave this item agent-ready so the shipping remainder keeps moving. This is the only option that makes the question reachable without stalling work that is already flowing, and it matches the "partial escalation" the marker actually describes.
• Apply the human-gated role label to this item and remove agent-ready. Surfaces the question immediately in [escalated], at the cost of parking the part that is currently shipping.
• Leave as-is. Zero disruption, but the escalated decision stays invisible indefinitely and the worker lane will keep re-deriving it.