A JSON state file ended in zeros after an unclean shutdown: quarantine it, then salvage every record you can

Disclosure: I'm the developer of the tool described here, and this post was drafted and published by an AI agent from the project's source code. Relaymote is unofficial; not affiliated with or endorsed by Anthropic.

Relaymote (MIT, Node.js) is a phone remote for Claude Desktop's Code-tab sessions. It keeps its task list in one file, registry.json: every queued, running and finished task, with its prompt, its dependencies and its id. It is the kind of file nobody thinks about until the day JSON.parse throws on it.

That day came after an unclean shutdown. The file had its normal size, but the last stretch of it was NUL bytes. This post is how the daemon now reacts to that: what it does at load time so it keeps running, and a separate relaymote salvage command that gets the tasks back.

What the damage looks like

The writes were already done the textbook way: write a temp file, fsync it, rename it over the real one. That protects against a half-written file from your own process. It does not fully protect you from the machine losing power around the rename, depending on the file system and what had actually reached the disk. The result we saw was a file whose length had been recorded but whose last blocks never arrived, so they read back as zeros.

The useful observation is about where the damage sits. The front of the file is intact. The break is a clean cut somewhere near the end, followed by padding. Almost every record is still there; only the parser gives up, because one bad byte fails the whole document.

Part 1: at load time, quarantine and keep going

The loader must not crash the daemon, and it must not "fix" the file in place. It does three things when parsing fails:

const q = FILE + '.corrupt-' + Date.now();
if (fs.existsSync(FILE)) {
  fs.renameSync(FILE, q);
  process.stderr.write(`registry.json could not be read; moved it to ${q}. Recover its tasks with: relaymote salvage\n`);
}

1. Rename, never delete. The damaged file is the only copy of those tasks. Moving it aside gives the daemon a clean slate and leaves the evidence untouched.
2. Say what to do next in the same log line. The person reading it at 2 a.m. should not have to find the docs.
3. Keep the id counter above the damage. Task ids are t0001, t0002, and so on. If the daemon starts empty with seq = 0, new tasks will reuse ids the salvage will later bring back. So before starting empty, it scans the raw text for every id and the old seq, and starts above the highest:

let seq = 0;
for (const m of String(raw).matchAll(/"t(\d+)"\s*:|"seq"\s*:\s*(\d+)/g))
  seq = Math.max(seq, Number(m[1] || m[2]) || 0);

A regex over broken JSON is fine here: it only needs to find numbers, not understand structure. And the new floor is saved straight away, not at the next write, so a second crash cannot lose it.

One Windows detail sits in front of all this: a file another process is renaming into place can be briefly locked (EPERM, EBUSY, EACCES). That is not corruption. The loader retries the read a few times with a short back-off before it decides the file is unreadable, so a normal save from another process never gets the registry quarantined.

Part 2: salvage, from cheapest repair to most expensive

salvage(raw) is a pure function (the tests call it directly) that tries three repairs in order and reports which one worked:

1. Trim the padding. Strip trailing NULs and whitespace, then parse. If the cut happened to land after the closing brace, this is all it takes.

2. Close the document after the last complete record. The file is written with JSON.stringify(state, null, 2), so every task object ends with a newline and exactly four spaces before its }. Find the last "\n }," (or failing that "\n }"), cut there, and append the closing braces for tasks and the root:

const cut = s.lastIndexOf('\n    },');
const j = JSON.parse(s.slice(0, cut + '\n    }'.length) + '\n  }\n}');

This leans on your own serializer's indentation, which is a fair thing to lean on: you wrote it, and it is deterministic. Everything before the last complete task comes back; only the task that was being written at the cut is lost. Any fields that came after tasks in the root object are lost too, which is why seq is recomputed from the recovered ids.

3. Scan for individual records. If the damage is in the middle, closing the document will not parse. So find each "tNNNN": {, walk forward counting braces (tracking whether you are inside a string, and escapes inside strings, so a } in a prompt doesn't end the object early), and try JSON.parse on just that slice. A mangled stretch now costs only the records it touched.

If all three fail, it returns null and the command says NOTHING_RECOVERABLE along with the file size and how much of it was padding, which is usually the whole explanation.

Part 3: merge into the live file without clobbering anything

By the time someone runs salvage, the daemon has been running on an empty registry and may have created new tasks. The recovered tasks are merged in, with a few rules:

• Live tasks keep their ids. A recovered task whose id is taken by a different live task gets the next free id. It is renumbered, never dropped, and the renumbering is printed.
• Dependencies follow the renumbering. If recovered task t0040 depended on t0039, and t0039 was renumbered, the dependsOn list is rewritten to match.
• Running it twice is harmless. Each task gets a fingerprint of its creation time and prompt. A recovered task whose fingerprint already exists under any id is counted as "already present", not added again.
• Each restored task is tagged with the corrupt file it came from, so you can tell restored tasks from new ones later.
• Dry run by default. Without --apply it only reports: method used, characters, padding, tasks recovered, how many would be added, how many are already present, the renumbering. With --apply it writes the merged registry with the same temp-file, fsync, rename sequence. It never modifies the corrupt file, so you can run it again.

What carries over

• When a state file fails to parse, move it aside and keep running. Never repair in place, never delete.
• Keep id counters above anything the damaged file mentions, and persist that floor immediately.
• Treat a briefly locked file on Windows as "retry", not "corrupt".
• Order repairs from cheapest to most expensive and report which one worked.
• Your own serializer's formatting is a legitimate anchor for finding record boundaries.
• Merges should renumber rather than overwrite, follow references, and be safe to repeat.

---

Relaymote is MIT-licensed: github.com/ashwarsadh/relaymote. The code is in lib/registry.js and lib/salvage.js. Unofficial; not affiliated with or endorsed by Anthropic.