sandcastle-resume

Files (1)

• SKILL.md

SKILL.md (first lines)

# Sandcastle Resume

Sandcastle isn't involved as a runner here — only its log is read. Recovery
means finishing the one ticket the crashed run was interrupted on, as a
background subagent working directly in the crashed worktree.

A run works through up to N **iterations** (`Iteration <k>/<N>` in the log), one
ticket per iteration. An iteration's ticket is the `#N` in its
`gh issue edit <N> ... --add-label "agent:in-progress"` line — `p-do-work`
removes that label only on clean completion. A crash lands inside the _last_
iteration only: every earlier iteration in the same log already claimed,
finished, and merged its ticket, so only the last one can hold stuck work. Scope
every diagnosis below to that last iteration — grepping the whole log for issue
mentions mixes in tickets that are already done.

## Steps

### 1. Resolve the target run

Both arguments are optional and order-free — tell them apart by shape, not by
position: a run argument is a timestamp or worktree/log name, a prompt argument
is a type word or a path under `.sandcastle/`. The prompt argument is used in
step 4; ignore it here.

The run argument is a worktree name (`sandcastle-<date>-<time>-<hex>`), a date
stamp (`<date>` or `<date>-<time>`), or a log filename
(`main-sandcastle-<date>-<time>-<hex>.log`). Logs live in `.sandcastle/logs/`,
worktrees in `.sandcastle/worktrees/`. A log and its worktree share the same
`<date>-<time>` prefix but generally have _different_ hex suffixes — pair them
by timestamp prefix, never by exact filename match.

**If a run argument is given**: resolve it to a log + worktree pair by matching
the timestamp prefix. If nothing matches, stop and say so.

**If no run argument is given**, scan `.sandcastle/logs/` newest → oldest, but
only the 3 most recent logs — older than that is out of scope, on the assumption
that a run left unfinished for that long has already been dealt with some other
way:

- A log that ends with `Run complete: agent finished after ...` is a completed
  run — add a one-line summary of it (each iteration's ticket, per above) to a
  running skip-list, and move to the next-older log.
- A log **without** that footer is unfinished, regardless of why it stopped — a
  recognized failure marker (step 2) isn't required, an unrecognized cause or
  even a log that just goes silent still counts. This is the aborted run; stop
  here.
- If all 3 have the completion footer, stop and report that no unfinished run
  was found in the recent window — do not keep scanning further back.

Show the skip-list (one line each), then the last ~5 lines of the aborted log,
then ask: "Is this the one you want?" — recommending this aborted run as the
default. Wait for confirmation before continuing.

### 2. Diagnose (best effort, informational only)

Grep the aborted log's tail for known failure markers:

- `Connection closed mid-response` → idle-sleep / connection drop.
- `session limit` → hit the session/usage limit.
- Neither → unrecognized failure; the raw tail already shown in step 1 is the
  report.

This does not change what happens next — every failure mode is resumed the same
way.

### 3. Identify the interrupted issue

Slice the aborted log to its last iteration (`grep -n '^Iteration'`, take the
final match to EOF) and check whether that slice contains its claim line.

- **Claimed**: issue #N is the interrupted one. Confirm it's still claimed —
  `gh issue list --label agent:in-progress --json number,title` — and
  cross-check against the resolved worktree's branch/commit history
  (`git -C <worktree> log`, `git -C <worktree> branch --show-current`) in case
  more than one run is stuck at once. If zero or more than one candidate
  survives the cross-check, stop and ask — do not guess which issue to resume.
  Otherwise continue to step 4.
- **Not claimed** (the crash landed before the last iteration's `gh issue edit`,
  e.g. right after `Agent started`): nothing is stuck — every ticket this run
  touched was already finished and merged by an earlier iteration. Report those
  issues and stop; skip steps 4 and 5, there is no subagent to spawn.

### 4. Resolve the prompt

The subagent's prompt is built from the sandcastle prompt file the crashed run
used. These live in `.sandcastle/` as `prompt.md` or `prompt-<type>.md`.

**If a prompt argument was given**, resolve it to that file — a bare type word
maps to `.sandcastle/prompt-<type>.md`, a path is taken as-is. If the file
doesn't exist, stop and say so.

**Otherwise infer it from the log.** A prompt file's shell expressions
(``!`...` `` lines) are expanded at run start and echoed into the log under
`Expanding shell expressions`, so the file whose expressions appear in the
aborted log is the one that ran. If only one prompt file exists, use it without
matching. If the match is inconclusive — neither side has shell expressions, or
several files match — fall back to `prompt.md`, and to `prompt-tickets.md` if
that's absent.

Report the resolved file and how it was resolved (argument, expression match, or
fallback) in one line.

### 5. Spawn the resuming subagent, in the background

Launch it directly into the resolved worktree — **do not pass
`isolation: "worktree"`** to the Agent tool. That option creates a _fresh_
worktree, which is exactly wrong here: the crashed run's uncommitted/staged
changes live only in the already-resolved worktree, and an isolated copy starts
empty and loses them. Set the agent's working directory to the resolved worktree
path instead (see below) and tell it in the prompt to `cd` there and treat it as
the repo root.

Build its prompt from the literal content of the prompt file resolved in step 4,
prefixed with:

> You are resuming a crashed AFK run. Your working directory for this entire
> task is the existing git worktree at: <worktree path>. It is currently on
> branch <branch>. Treat that path as your repo root — cd there first and work
> directly in it. Do not create any new worktree.

From tregusti/skills, MIT.

More from tregusti/skills