shipback-sftp 0.1.0 → 0.2.1

package/README.md

@@ -11,13 +11,23 @@ Shipback deploys a folder to any SFTP host: cPanel, Plesk, DirectAdmin, a plain
 can be undone with one command. You can run it yourself, script it, or hand it to Claude Code, Cursor or
 any MCP client.
 
+**[The undo promise](UNDO-PROMISE.md):** one command puts the site back byte for byte, even after a deploy that
+was cut off halfway. It never overwrites a live edit. Each of the thirteen lines in the promise has its own test, and
+if undo ever breaks one of them, that's the first bug I fix.
+
 - **Backup before every overwrite.** The server's copy of each file a deploy replaces is saved into
   `_backup-<time>/` on the server, before the upload starts.
+- **Never half a file.** Each file goes up beside the live one and is swapped in whole, so a dropped connection
+  leaves the old file, not a broken one.
 - **One-command undo.** `--restore` puts those files back and removes the files that deploy added.
 - **It won't undo over a live edit.** If someone changed a file on the server after the deploy, restore
   stops and names the file. Nothing is touched unless you pass `--force`, and even then the edited copy is
   backed up first.
 - **Restores can be undone too.** A restore backs up what it replaces, the same way a deploy does.
+- **One run at a time.** A deploy or restore holds a lock on the site while it writes. A second one is turned away
+  with nothing changed, so an agent and a person can't deploy over each other.
+- **Stays inside the site.** Deploy and undo won't write through a symlink or over a special file on the server,
+  so a symlinked folder can't carry a write somewhere else.
 - **Safe for agents.** The MCP server has no switch to delete server files or skip the backup. A deploy
   only runs the exact plan the agent previewed: if a file changed in between, it refuses.
 - **Spots the drift.** `--pull --dry-run` shows what changed on the server since your last deploy, so
@@ -28,22 +38,24 @@ and Linux with Node 18, 20 and 22 on every push. Passwords are kept in the OS ke
 pass through the model.
 
 **It has run in production.** The deploy engine underneath has shipped [aldo.today](https://aldo.today) 235 times
-since September 2026 (2,907 files to a cPanel host). Restore and the MCP server are new in 0.1.
+since September 2026 (2,907 files to a cPanel host). Restore and the MCP server are new since 0.1, and the
+cut-off handling behind the promise is new in 0.2.
 
 ## Quick start
 
 ```bash
-git clone https://github.com/aldohushi1-stack/shipback-sftp.git
-cd shipback-sftp
-npm install
-cp sites.example.json sites.json      # then edit it
-node bin/cli.js mysite --dry-run      # see the plan; asks for the password once and stores it
-node bin/cli.js mysite                # deploy
-node bin/cli.js mysite --restore      # changed your mind? undo it
+npm install -g shipback-sftp          # installs the shipback and shipback-mcp commands
+cd ~/sites                            # any folder with a sites.json in it (format below)
+shipback mysite --dry-run             # see the plan; asks for the password once and stores it
+shipback mysite                       # deploy
+shipback mysite --restore             # changed your mind? undo it
 ```
 
-`npm link` in the folder installs it as the `shipback` and `shipback-mcp` commands, so `node bin/cli.js mysite`
-becomes `shipback mysite`.
+No global install? `npx -p shipback-sftp shipback mysite --dry-run` works the same way. `--sites <file>`
+points at a `sites.json` in another folder.
+
+From source: `git clone https://github.com/aldohushi1-stack/shipback-sftp.git`, `npm install`, then
+`node bin/cli.js` wherever these docs say `shipback`.
 
 `sites.json`, one entry per site:
 
@@ -70,19 +82,20 @@ first. Use `"privateKeyPath"` instead of a password if your host has your key.
 ## Commands
 
 ```bash
-node bin/cli.js <site> --dry-run                 # what a deploy would upload
-node bin/cli.js <site>                           # deploy: backup, upload, record
-node bin/cli.js <site> --local <folder>          # deploy a different folder than localDir
-node bin/cli.js <site> --pull --dry-run          # what changed on the server since the last deploy?
-node bin/cli.js <site> --pull                    # bring those changes down (local copies backed up first)
-node bin/cli.js <site> --backups                 # list backups: what each run overwrote, added, deleted
-node bin/cli.js <site> --restore --dry-run       # what an undo of the latest deploy would do
-node bin/cli.js <site> --restore [<backup>]      # undo it (or name an older _backup-… folder)
-node bin/cli.js <site> --prune --keep 10         # tidy old backups; refuses any holding the only copy of a file
-node bin/cli.js --history [site]                 # what went up, when, from where
+shipback <site> --dry-run                 # what a deploy would upload
+shipback <site>                           # deploy: backup, upload, record
+shipback <site> --local <folder>          # deploy a different folder than localDir
+shipback <site> --pull --dry-run          # what changed on the server since the last deploy?
+shipback <site> --pull                    # bring those changes down (local copies backed up first)
+shipback <site> --backups                 # list backups: what each run overwrote, added, deleted
+shipback <site> --restore --dry-run       # what an undo of the latest deploy would do
+shipback <site> --restore [<backup>]      # undo it (or name an older _backup-… folder)
+shipback <site> --prune --keep 10         # tidy old backups; refuses any holding the only copy of a file
+shipback --history [site]                 # what went up, when, from where
 ```
 
-Add `--json` to any command for machine-readable output. A refused restore exits with code 4.
+Add `--json` to any command for machine-readable output. A refused restore exits with code 4, and a run turned away
+because another one is writing to the site exits with code 5.
 
 `--mirror` (delete server files that aren't in the local folder) and `--no-backup` exist for humans who
 know they want them. The agent tools don't offer them, and the [guard hook](#claude-code-guard-hook)
@@ -93,7 +106,18 @@ blocks Claude from typing them.
 Each deploy writes `_backup-YYYY-MM-DD-HHMM/` in the remote root. It holds:
 
 - the server's copy of every file the deploy **overwrote** or **deleted**
-- `.backup.json`, a record of what the deploy **added**, and a SHA-256 of every file it left on the server
+- `.backup.json`, a record of what the deploy **added**, a SHA-256 of every file it left on the server, and a
+  SHA-256 of every copy it saved, so a damaged copy is never put back
+
+The record says `saving` until every copy is made. A deploy cut off before then hasn't changed anything, and
+`--restore` says so. New files go up as `.shipback-part-<name>` beside the live file and are renamed over it in one
+step, keeping its permissions. Listings hide part files, and the next deploy or restore clears any that are left.
+
+While a deploy, upload, restore or prune writes, it holds `.shipback-lock` in the remote root and refreshes it every
+30 seconds. The lock is never deployed, pulled or listed. A lock goes stale, and the next run takes it over, when its
+process on this computer has ended or nothing has refreshed it for 2 minutes. If the system has reused that process
+ID, the lock just waits out the 2 minutes; a run that's still going is never mistaken for a finished one. So a run that was cut off never leaves
+a site locked for long.
 
 `--restore` reads that record and checks each live file first:
 
@@ -104,19 +128,20 @@ Each deploy writes `_backup-YYYY-MM-DD-HHMM/` in the remote root. It holds:
 | different from both | **conflict**: stops, names the file, changes nothing (`--force` overrides) |
 
 Before writing anything, restore saves the current live files into a new `_backup-…` folder with its own
-record, so `--restore` on that folder takes you forward again. It also clears the restored paths from
+record, so `--restore` on that folder takes you forward again. If a restore is cut off, plain `--restore` sees that
+the latest run is an unfinished restore and finishes it. It also clears the restored paths from
 `.deploy-manifest.json`, so the next deploy compares them by content instead of trusting stale hashes.
 
 Backup folders are skipped by deploys and pulls, and are never deleted except by `--prune`.
 
 ## Use it from an AI agent (MCP)
 
-`bin/mcp.js` is an MCP server over stdio.
+`shipback-mcp` (`bin/mcp.js`) is an MCP server over stdio.
 
 **Claude Code**
 
 ```bash
-claude mcp add shipback-sftp -- node /path/to/shipback-sftp/bin/mcp.js --sites /path/to/sites.json
+claude mcp add shipback-sftp -- npx -y -p shipback-sftp shipback-mcp --sites /path/to/sites.json
 ```
 
 **Cursor, Claude Desktop, and others** (`mcp.json` / `claude_desktop_config.json`):
@@ -125,14 +150,18 @@ claude mcp add shipback-sftp -- node /path/to/shipback-sftp/bin/mcp.js --sites /
 {
   "mcpServers": {
     "shipback-sftp": {
-      "command": "node",
-      "args": ["/path/to/shipback-sftp/bin/mcp.js", "--sites", "/path/to/sites.json"]
+      "command": "npx",
+      "args": ["-y", "-p", "shipback-sftp", "shipback-mcp", "--sites", "/path/to/sites.json"]
     }
   }
 }
 ```
 
-Run any CLI command for a site once first (for example `node bin/cli.js mysite --backups`). That stores
+On Windows, if the client can't start `npx`, use `"command": "cmd"` with `"/c", "npx"` at the front of
+`args`. After a global install, `"command": "shipback-mcp"` works too, and from a clone it's `node` with
+`bin/mcp.js` as the first arg.
+
+Run any CLI command for a site once first (for example `shipback mysite --backups`). That stores
 the password in the OS keychain, where the MCP server reads it. The model never sees it. For CI you can set
 `SFTP_PASSWORD` in the server's environment instead.
 
@@ -172,7 +201,8 @@ one-off uploads, browse the server, and see history. It only answers requests fr
 
 If Claude also runs the CLI directly, add `bin/claude-guard.js` as a PreToolUse hook. It blocks
 `--mirror` and `--no-backup` in shell commands, queue files and API calls, and tells Claude why. You can
-still run them yourself in a terminal.
+still run them yourself in a terminal. After `npm install -g shipback-sftp`, the file is in the folder
+`npm root -g` prints, under `shipback-sftp/bin/`.
 
 ```json
 {
@@ -193,7 +223,8 @@ still run them yourself in a terminal.
 npm test
 ```
 
-The suite uses `node:test` and needs no network. Deploy, restore, the CLI and the MCP server are each
+The suite uses `node:test` and needs no network. `test/promise.test.js` holds one test per line of the
+[undo promise](UNDO-PROMISE.md). Deploy, restore, the CLI and the MCP server are each
 also exercised end to end against a real SFTP server started inside the test run.
 
 ## Limits
@@ -204,6 +235,8 @@ also exercised end to end against a real SFTP server started inside the test run
   hosting account. Keep your host's own backups too.
 - Files over 8 MB with the same size on both sides are assumed unchanged when there is no manifest hash
   to compare.
+- What undo doesn't cover (databases, `--no-backup` deploys, pruned backups and so on) is listed in
+  [the undo promise](UNDO-PROMISE.md#what-it-doesnt-cover).
 
 ## License
 

package/UNDO-PROMISE.md

@@ -0,0 +1,53 @@
+# The undo promise
+
+Any deploy Shipback makes can be undone with one command:
+
+```bash
+shipback mysite --restore
+```
+
+Agents get the same thing as `preview_restore` then `restore`. Here is exactly what it does. Each line has a test with
+the same number in [`test/promise.test.js`](test/promise.test.js). Those tests run on every push, on Windows, macOS
+and Linux, and compare every byte on the server, not a sample.
+
+| | When you undo a deploy |
+| --- | --- |
+| **P1** | Every file it replaced or deleted comes back byte for byte. Every file it added is removed, along with any folder it created for them. Nothing else on the server is touched: uploads, form data and `.well-known` stay as they are. |
+| **P2** | If the deploy was cut off part way (Wi-Fi dropped, laptop lid shut), the live site never had half a file on it, and the same one command still undoes it. No `--force`. |
+| **P3** | That holds on servers that can't swap a file in one step too. |
+| **P4** | If it was cut off while it was still saving backups, it hadn't changed anything yet. Undo says so and doesn't guess. |
+| **P5** | If the backup can't be saved (a full disk, say), nothing goes up. |
+| **P6** | If the undo itself is cut off, run it again and it finishes. |
+| **P7** | If someone changed one of those files on the server after the deploy, undo stops, names the file and changes nothing at all. You decide what happens next. |
+| **P8** | A backup copy that's been damaged since is never written back, even with `--force`. |
+| **P9** | The undo can be undone. |
+| **P10** | All of this works through a real SFTP server, and replaced files keep their permissions. |
+| **P11** | A dropped connection fails the deploy out loud and tells you how to undo it. It never stops in silence. |
+| **P12** | Only one deploy or undo writes to a site at a time. A second one is turned away without changing anything, so two runs can never get mixed into one backup. A lock left behind by a run that was cut off clears itself. |
+| **P13** | Undo never touches anything outside the site folder, even if a backup record has been tampered with to say it should, and neither undo nor deploy writes through a symlink or over a special file on the server. A record that can't be read is refused, never guessed at. |
+
+These have also been run on a real cPanel host, including cutting the connection halfway through a deploy and running
+two deploys at once.
+
+## If it doesn't
+
+If undo ever fails to do one of those things, [open an "Undo didn't work" issue](https://github.com/aldohushi1-stack/shipback-sftp/issues/new?template=undo_failed.yml).
+
+- It's the first thing I fix, ahead of everything else.
+- I'll help you get your files back by hand. Everything the deploy replaced is still in its `_backup-…` folder on your server.
+- The fix ships with a test built from your case, so it can't happen again.
+
+## What it doesn't cover
+
+- **Deploys made with `--no-backup`.** They have nothing to undo from. The agent tools can't make them.
+- **Backups that are gone.** Undo needs that deploy's `_backup-…` folder. `--prune` will remove old ones if you ask, and so can you or your host.
+- **Anything outside the site folder:** databases, server settings, cron jobs, email. The site folder itself may be a
+  symlink (cPanel's `www` → `public_html` is normal), and Shipback follows that one. It won't follow any symlink inside it.
+- **Backups made before 0.2.** Those still restore, but they don't carry the checksums behind P4 and P8.
+- **File dates and owners.** Restored files get the current time. A file brought back after a deploy deleted it gets the server's default permissions.
+- **Losing the hosting account.** Backups sit on the same server as the site. Keep your host's own backups too.
+
+This is a promise about what the software does and how I'll treat it when it doesn't. It isn't insurance, and the
+MIT licence's "no warranty" still stands.
+
+Aldo Hushi, 20 October 2026

package/bin/cli.js

@@ -119,7 +119,8 @@ ${site.host}:${remoteRoot}  restore from ${ev.backup}${ev.legacy ? '  (older bac
 `);
     } else if (ev.type === 'conflict') console.log(`  CONFLICT ${ev.path}: ${ev.why}`);
     else if (ev.type === 'restore') console.log(`  restore ${ev.path}`);
-    else if (ev.type === 'error') console.error(`  ERROR   ${ev.message}`);
+    else if (ev.type === 'error') console.error(`  ERROR   ${ev.message}${ev.undo ? `
+          ${ev.undo}` : ''}`);
   };
   const common = { localDir, remoteRoot, remoteFs: rfs, dryRun: !!args.dryRun, backup: args.backup !== false, mirror: !!args.mirror, ignore: site.ignore, onEvent };
   try {
@@ -127,12 +128,14 @@ ${site.host}:${remoteRoot}  restore from ${ev.backup}${ev.legacy ? '  (older bac
       const list = await describeBackups({ remoteRoot, remoteFs: rfs });
       if (args.json) console.log(JSON.stringify(list, null, 2));
       else if (!list.length) console.log('No backups on the server.');
-      else for (const b of list) console.log(`  ${b.name.padEnd(28)} ${b.legacy ? `${b.files} files (older backup, no record)` : `${b.action.padEnd(8)} ${b.overwritten} overwritten, ${b.added} added, ${b.deleted} deleted${b.from ? '  (undo of ' + b.from + ')' : ''}`}`);
+      else for (const b of list) console.log(`  ${b.name.padEnd(28)} ${b.legacy ? `${b.files} files (older backup, no record)` : `${b.action.padEnd(8)} ${b.overwritten} overwritten, ${b.added} added, ${b.deleted} deleted${b.from ? '  (undo of ' + b.from + ')' : ''}${b.status === 'saving' ? '  [cut off before changing anything]' : b.status ? '  [cut off part way]' : ''}`}`);
       return;
     }
     if (args.restore) {
       const s = await runRestore({ remoteRoot, remoteFs: rfs, name: args.name, dryRun: !!args.dryRun, force: !!args.force, onEvent });
-      if (s.refused) { console.log(`Refused: ${s.conflicts.length} file(s) changed on the server after that run. Nothing was changed. Check them, then add --force to restore anyway (the live copies are backed up first).`); process.exitCode = 4; }
+      if (s.resumed) console.log(`(${s.resumed} is a restore that was cut off, so this finishes it: restoring ${s.backup})`);
+      if (s.stoppedEarly) console.log(`${s.backup} was cut off while it was still saving backups, before it changed any live file. Nothing to undo.`);
+      else if (s.refused) { console.log(`Refused: ${s.conflicts.length} file(s) changed on the server after that run. Nothing was changed. Check them, then add --force to restore anyway (the live copies are backed up first).`); process.exitCode = 4; }
       else if (s.dryRun) console.log('Dry run — nothing was changed.');
       else console.log(`Done: ${s.put.length} put back, ${s.remove.length} removed${s.undoBackupDir ? `. Undo this with --restore ${s.undoBackupDir.split('/').pop()}` : ''}.`);
       if (!s.dryRun) await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', remoteDir: remoteRoot, startedAt, summary: s })).catch(() => {});
@@ -152,7 +155,7 @@ ${site.host}:${remoteRoot}  restore from ${ev.backup}${ev.legacy ? '  (older bac
     }
     if (args.json) console.log(JSON.stringify(s));
   } catch (e) {
-    process.exitCode = 3;
+    process.exitCode = e.code === 'ELOCKED' ? 5 : 3;
     await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', localDir, remoteDir: remoteRoot, startedAt, error: e.message })).catch(() => {});
   }
   finally { await rfs.close(); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipback-sftp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "SFTP deploys to shared hosting that you, a script or an AI agent can undo: backup before every overwrite, one-command restore that won't clobber live edits, and an MCP server.",
   "keywords": [
     "sftp",
@@ -32,6 +32,7 @@
     "start.bat",
     "sites.example.json",
     "README.md",
+    "UNDO-PROMISE.md",
     "LICENSE"
   ],
   "scripts": {

package/src/backup.js

@@ -2,8 +2,10 @@
 // Copy the server's current copy of each file into <root>/_backup-<stamp>/<path> before it is overwritten or deleted.
 // A deploy also writes <backup>/.backup.json — what it overwrote, added and deleted, and the sha256 of what it
 // uploaded — so restore.js can undo it and tell when a live file was edited after the deploy.
+const crypto = require('node:crypto');
 const posix = require('node:path').posix;
-const { BACKUP_PREFIX } = require('./diff');
+const { BACKUP_PREFIX, MANIFEST_NAME } = require('./diff');
+const { writeLive, isHidden } = require('./remote-fs');
 
 const BACKUP_INFO = '.backup.json';
 
@@ -20,11 +22,17 @@ async function freeBackupDir(remoteFs, root, stamp) {
   return dir;
 }
 
-/** backupFiles({ remoteFs, root, paths, stamp | backupDir, onEvent }) → { backupDir, copied } */
+const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
+
+/**
+ * backupFiles({ remoteFs, root, paths, stamp | backupDir, onEvent }) → { backupDir, copied, was }
+ *   was: Map path → sha256 of the copy saved, so restore can check the copy is still intact before using it
+ */
 async function backupFiles({ remoteFs, root, paths, stamp = makeStamp(), backupDir, onEvent = () => {} }) {
   root = root.replace(/\/$/, '');
   backupDir = backupDir || `${root}/${BACKUP_PREFIX}${stamp}`;
   const copied = [];
+  const was = new Map();
   const madeDirs = new Set();
   for (const rel of paths) {
     const src = `${root}/${rel}`;
@@ -36,26 +44,51 @@ async function backupFiles({ remoteFs, root, paths, stamp = makeStamp(), backupD
     const data = await remoteFs.readFile(src);
     await remoteFs.writeFile(dest, data);
     copied.push(rel);
+    was.set(rel, sha256(data));
     onEvent({ type: 'backup', path: rel, bytes: data.length, to: dest });
   }
-  return { backupDir, copied };
+  return { backupDir, copied, was };
 }
 
 /**
  * writeBackupInfo({ remoteFs, backupDir, info })
- *   info: { action, at, overwritten: [{ path, sha256 }], added: [{ path, sha256 }], deleted: [{ path }], from? }
+ *   info: { action, at, overwritten: [{ path, sha256, was }], added: [{ path, sha256 }], deleted: [{ path, was }], from? }
  *   sha256 = the content the run left at that path, so a later restore can tell if it was edited since.
+ *   was = the sha256 of the copy saved in the backup folder (from 0.2; older records have none).
+ *   status (from 0.2): 'saving' while the copies are being made, so a run cut off then is known to have changed
+ *   nothing; a restore also says 'running' while it writes, so cutting it off can be finished by running it again.
+ *   No status = the record is whole. It is swapped in whole too, never left half written.
  */
 async function writeBackupInfo({ remoteFs, backupDir, info }) {
   await remoteFs.mkdirp(backupDir);
-  await remoteFs.writeFile(`${backupDir}/${BACKUP_INFO}`, JSON.stringify({ version: 1, tool: 'shipback-sftp', ...info }, null, 1));
+  await writeLive(remoteFs, `${backupDir}/${BACKUP_INFO}`, { data: Buffer.from(JSON.stringify({ version: 1, tool: 'shipback-sftp', ...info }, null, 1)) });
+}
+
+/** A path a record may name: relative, inside the site, and not one of Shipback's own files. */
+function siteRelative(p) {
+  if (typeof p !== 'string' || !p || p.startsWith('/') || p.includes('\\') || p.includes('\0') || /^[A-Za-z]:/.test(p)) return false;
+  const segs = p.split('/');
+  return segs.every(s => s && s !== '.' && s !== '..' && !s.startsWith(BACKUP_PREFIX)) && p !== MANIFEST_NAME && !isHidden(p);
 }
 
+/**
+ * The run's record, or null if the folder has none (a backup made before .backup.json existed).
+ * A record that can't be read, or that names any path outside the site, throws: restore never guesses from it,
+ * and never falls back to putting files back unchecked.
+ */
 async function readBackupInfo(remoteFs, backupDir) {
-  try {
-    const info = JSON.parse((await remoteFs.readFile(`${backupDir}/${BACKUP_INFO}`)).toString('utf8'));
-    return info && info.version === 1 ? info : null;
-  } catch { return null; }
+  if (!(await remoteFs.stat(`${backupDir}/${BACKUP_INFO}`))) return null;
+  let info;
+  try { info = JSON.parse((await remoteFs.readFile(`${backupDir}/${BACKUP_INFO}`)).toString('utf8')); }
+  catch (e) { throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is damaged (${e.message.split('\n')[0]}), so it can't be restored safely`); }
+  if (!info || info.version !== 1) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is not a record this version understands`);
+  for (const key of ['overwritten', 'added', 'deleted']) {
+    if (!Array.isArray(info[key])) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is damaged (no "${key}" list), so it can't be restored safely`);
+    for (const e of info[key]) {
+      if (!e || !siteRelative(e.path)) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} names a path outside the site (${JSON.stringify(e && e.path)}). Nothing was changed`);
+    }
+  }
+  return info;
 }
 
-module.exports = { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, BACKUP_INFO };
+module.exports = { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, siteRelative, BACKUP_INFO };

package/src/deploy.js

@@ -5,6 +5,8 @@ const posix = path.posix;
 const { scanLocal, loadIgnore, dropIgnored, sha256File } = require('./manifest');
 const { plan: makePlan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX } = require('./diff');
 const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo } = require('./backup');
+const { writeLive, outsideReason } = require('./remote-fs');
+const { withLock } = require('./lock');
 
 const isBackupDir = name => name.startsWith(BACKUP_PREFIX);
 
@@ -13,6 +15,15 @@ async function readRemoteManifest(remoteFs, root) {
   catch { return null; }
 }
 
+/** Throw before anything changes if any path would write through a symlink or over a special file. */
+async function refuseOutside(remoteFs, root, paths) {
+  const folders = new Map();
+  for (const p of paths) {
+    const why = await outsideReason(remoteFs, root, p, folders);
+    if (why) throw new Error(`Refused: ${why}. Nothing was changed. Ignore that path in sites.json or .deployignore, or replace the symlink with a real folder.`);
+  }
+}
+
 /** Preview only: scan both sides and return the plan. */
 async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, ignore, onEvent = () => {} }) {
   const root = remoteRoot.replace(/\/$/, '');
@@ -25,6 +36,7 @@ async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, i
   const remoteListing = rootStat ? dropIgnored(await remoteFs.listRecursive(root, { skipDir: isBackupDir }), await loadIgnore(localDir, ignore)) : [];
   const remoteManifest = rootStat ? await readRemoteManifest(remoteFs, root) : null;
   const plan = makePlan({ local, remoteManifest, remoteListing, mirror });
+  if (rootStat) await refuseOutside(remoteFs, root, [...plan.upload.map(u => u.path), ...plan.delete]);
   if (plan.verify.length) await resolveVerify(plan, { readFile: p => remoteFs.readFile(`${root}/${p}`), onEvent });
   onEvent({ type: 'plan', plan, localCount: local.length, remoteCount: remoteListing.length, remoteExists: !!rootStat });
   return { local, plan, remoteExists: !!rootStat };
@@ -34,7 +46,12 @@ async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, i
  * runDeploy({ localDir, remoteRoot, remoteFs, dryRun, backup, mirror, ignore, now, onEvent })
  * → { dryRun, plan, uploaded, backedUp, backupDir, deleted, bytes }
  */
-async function runDeploy({ localDir, remoteRoot, remoteFs, dryRun = false, backup = true, mirror = false, ignore, now = new Date(), onEvent = () => {} }) {
+async function runDeploy(opts) {
+  if (opts.dryRun) return deployNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'deploy', createRoot: true, onEvent: opts.onEvent }, () => deployNow(opts));
+}
+
+async function deployNow({ localDir, remoteRoot, remoteFs, dryRun = false, backup = true, mirror = false, ignore, now = new Date(), onEvent = () => {} }) {
   const root = remoteRoot.replace(/\/$/, '');
   const summary = { dryRun, plan: null, uploaded: [], backedUp: [], backupDir: null, deleted: [], bytes: 0 };
   try {
@@ -44,30 +61,32 @@ async function runDeploy({ localDir, remoteRoot, remoteFs, dryRun = false, backu
 
     if (!remoteExists) { await remoteFs.mkdirp(root); onEvent({ type: 'mkdir', path: root }); }
 
-    // 1. backup everything about to be overwritten or deleted, plus .backup.json so restore can undo this run
+    // 1. backup everything about to be overwritten or deleted, plus .backup.json so restore can undo this run.
+    //    The record says 'saving' until every copy is made: cut off before that, the run has changed nothing.
     if (backup && (plan.upload.length || plan.delete.length)) {
       const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      await writeBackupInfo({ remoteFs, backupDir, info: { action: 'deploy', at: now.toISOString(), status: 'saving', overwritten: [], added: [], deleted: [] } });
       const targets = [...plan.upload.filter(u => u.reason === 'changed').map(u => u.path), ...plan.delete];
       const res = await backupFiles({ remoteFs, root, paths: targets, backupDir, onEvent });
       const copied = new Set(res.copied);
       const sha = new Map(local.map(f => [f.path, f.sha256]));
       await writeBackupInfo({ remoteFs, backupDir, info: {
         action: 'deploy', at: now.toISOString(),
-        overwritten: plan.upload.filter(u => copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path) })),
+        overwritten: plan.upload.filter(u => copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path), was: res.was.get(u.path) })),
         added: plan.upload.filter(u => !copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path) })),
-        deleted: plan.delete.filter(p => copied.has(p)).map(p => ({ path: p })),
+        deleted: plan.delete.filter(p => copied.has(p)).map(p => ({ path: p, was: res.was.get(p) })),
       } });
       summary.backedUp = res.copied;
       summary.backupDir = backupDir;
     }
 
-    // 2. upload new + changed
+    // 2. upload new + changed, each swapped in whole (a dropped line leaves the old file, not half a new one)
     const madeDirs = new Set([root]);
     for (const u of plan.upload) {
       const dest = `${root}/${u.path}`;
       const dir = posix.dirname(dest);
       if (!madeDirs.has(dir)) { await remoteFs.mkdirp(dir); madeDirs.add(dir); }
-      await remoteFs.uploadFile(path.join(localDir, ...u.path.split('/')), dest);
+      await writeLive(remoteFs, dest, { localPath: path.join(localDir, ...u.path.split('/')) });
       summary.uploaded.push(u.path); summary.bytes += u.size;
       onEvent({ type: 'upload', path: u.path, bytes: u.size, reason: u.reason, done: summary.uploaded.length, total: plan.upload.length });
     }
@@ -87,34 +106,42 @@ async function runDeploy({ localDir, remoteRoot, remoteFs, dryRun = false, backu
     onEvent({ type: 'done', summary });
     return summary;
   } catch (err) {
-    onEvent({ type: 'error', message: err.message, summary });
+    // a deploy that stopped part way is undone like any other: everything it touched is in its backup record
+    if (summary.backupDir && summary.uploaded.length) err.undo = `${summary.uploaded.length} of ${summary.plan.upload.length} files went up before it stopped. --restore undoes them (${posix.basename(summary.backupDir)}).`;
+    onEvent({ type: 'error', message: err.message, undo: err.undo, summary });
     throw err;
   }
 }
 
 /** Ad-hoc upload of named local files into a remote dir (with backup of anything overwritten). */
-async function uploadFiles({ files, remoteDir, remoteFs, backup = true, now = new Date(), onEvent = () => {} }) {
+function uploadFiles(opts) {
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteDir, action: 'upload', createRoot: true, onEvent: opts.onEvent }, () => uploadNow(opts));
+}
+
+async function uploadNow({ files, remoteDir, remoteFs, backup = true, now = new Date(), onEvent = () => {} }) {
   // files: [{ name, localPath, size }]
   const root = remoteDir.replace(/\/$/, '');
   const summary = { uploaded: [], backedUp: [], backupDir: null, bytes: 0 };
   try {
     await remoteFs.mkdirp(root);
+    await refuseOutside(remoteFs, root, files.map(f => f.name));
     if (backup && files.length) {
       const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      await writeBackupInfo({ remoteFs, backupDir, info: { action: 'upload', at: now.toISOString(), status: 'saving', overwritten: [], added: [], deleted: [] } });
       const res = await backupFiles({ remoteFs, root, paths: files.map(f => f.name), backupDir, onEvent });
       const copied = new Set(res.copied);
       const shas = new Map();
       for (const f of files) shas.set(f.name, await sha256File(f.localPath));
       await writeBackupInfo({ remoteFs, backupDir, info: {
         action: 'upload', at: now.toISOString(),
-        overwritten: files.filter(f => copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name) })),
+        overwritten: files.filter(f => copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name), was: res.was.get(f.name) })),
         added: files.filter(f => !copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name) })),
         deleted: [],
       } });
       summary.backedUp = res.copied; summary.backupDir = backupDir;
     }
     for (const f of files) {
-      await remoteFs.uploadFile(f.localPath, `${root}/${f.name}`);
+      await writeLive(remoteFs, `${root}/${f.name}`, { localPath: f.localPath });
       summary.uploaded.push(f.name); summary.bytes += f.size || 0;
       onEvent({ type: 'upload', path: f.name, bytes: f.size || 0, reason: 'upload', done: summary.uploaded.length, total: files.length });
     }

package/src/lock.js

@@ -0,0 +1,92 @@
+'use strict';
+// One run at a time per site. Deploy, upload, restore and prune hold <root>/.shipback-lock while they write: two
+// at once would interleave their backups, and an undo could then pick up half of each. A second run is refused
+// and told who holds the lock.
+//
+// A run that is cut off can't take its lock away, so a lock counts as stale (and is taken over) when:
+//   · it was taken on this computer by a process that has ended, or by this process for a run that is over, or
+//   · nobody has refreshed it for STALE_MS (the holder rewrites it every HEARTBEAT_MS while it runs)
+//
+// withLock({ remoteFs, root, action, createRoot, onEvent }, fn) → fn's result, the lock held throughout.
+// Only a deploy or upload creates a missing root; a restore or prune there has nothing to protect and fails by itself.
+const crypto = require('node:crypto');
+const os = require('node:os');
+const { LOCK_NAME } = require('./remote-fs');
+
+const HEARTBEAT_MS = 30000;
+const STALE_MS = 120000;
+const held = new Set(); // tokens this process holds right now
+
+// the lock sits in the web root, so it carries a hash of the computer's name, not the name
+const machine = () => crypto.createHash('sha256').update(os.hostname()).digest('hex').slice(0, 12);
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+async function readLock(remoteFs, file) {
+  try { return JSON.parse((await remoteFs.readFile(file)).toString('utf8')); } catch { return null; }
+}
+
+/** Why a lock can be taken over, or null if its run may still be going. */
+function staleReason(lock, mtime, now) {
+  if (lock && lock.machine === machine() && Number.isInteger(lock.pid)) {
+    if (lock.pid === process.pid ? !held.has(lock.token) : !pidAlive(lock.pid)) return 'its run on this computer has ended';
+  }
+  if (now - mtime > STALE_MS) return `nothing has refreshed it for ${Math.round((now - mtime) / 60000)} min`;
+  return null;
+}
+
+class LockedError extends Error {
+  constructor(lock) {
+    const who = lock && lock.machine === machine() ? 'on this computer' : 'from another computer';
+    super(`Another ${lock && lock.action || 'run'} is writing to this site right now (started ${lock && lock.at || 'just now'}, ${who}). `
+      + 'Nothing was changed. Try again when it finishes. A lock left by a run that was cut off clears itself within 2 minutes.');
+    this.code = 'ELOCKED';
+  }
+}
+
+async function acquire({ remoteFs, root, action, now = Date.now, onEvent = () => {} }) {
+  const file = `${root}/${LOCK_NAME}`;
+  const token = crypto.randomBytes(8).toString('hex');
+  const body = () => Buffer.from(JSON.stringify({ tool: 'shipback-sftp', action, token, pid: process.pid, machine: machine(), at: new Date(now()).toISOString() }));
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (await remoteFs.createExclusive(file, body())) {
+      held.add(token);
+      let beat = Promise.resolve();
+      const timer = setInterval(() => { beat = beat.then(() => remoteFs.writeFile(file, body())).catch(() => {}); }, HEARTBEAT_MS);
+      if (timer.unref) timer.unref();
+      return async () => {
+        clearInterval(timer);
+        held.delete(token);
+        await beat;
+        const cur = await readLock(remoteFs, file);
+        if (cur && cur.token === token) await remoteFs.remove(file).catch(() => {});
+      };
+    }
+    const st = await remoteFs.stat(file);
+    if (!st) continue; // released between the two calls
+    const lock = await readLock(remoteFs, file);
+    const why = staleReason(lock, st.mtime, now());
+    if (!why) throw new LockedError(lock);
+    onEvent({ type: 'stale-lock', action: lock && lock.action, at: lock && lock.at, why });
+    await remoteFs.remove(file).catch(() => {});
+  }
+  throw new LockedError(await readLock(remoteFs, file));
+}
+
+async function withLock({ remoteFs, root, action, createRoot = false, now, onEvent = () => {} }, fn) {
+  root = root.replace(/\/$/, '');
+  let release = null;
+  try {
+    const exists = await remoteFs.stat(root);
+    if (exists || createRoot) {
+      if (!exists) await remoteFs.mkdirp(root);
+      release = await acquire({ remoteFs, root, action, now, onEvent });
+    }
+  } catch (err) { onEvent({ type: 'error', message: err.message, code: err.code }); throw err; }
+  try { return await fn(); }
+  finally { if (release) await release().catch(() => {}); } // a dropped connection can't release: the lock then goes stale
+}
+
+module.exports = { withLock, LockedError, STALE_MS, HEARTBEAT_MS };

package/src/mcp.js

@@ -153,7 +153,9 @@ function createMcp(opts = {}) {
       return {
         planId: restorePlanId(site, s), site: site.name, backup: s.backup, undoes: s.action, legacy: s.legacy || undefined,
         putBack: cap(s.put), remove: cap(s.remove), alreadyRight: s.same.length, conflicts: s.conflicts,
-        note: s.conflicts.length ? 'Some live files were changed after that run. Show the user the conflicts; restore refuses them unless force is true.'
+        resumes: s.resumed || undefined,
+        note: s.stoppedEarly ? 'That run was cut off while saving its backups, before it changed any live file. There is nothing to undo.'
+          : s.conflicts.length ? 'Some live files were changed after that run. Show the user the conflicts; restore refuses them unless force is true.'
           : s.put.length || s.remove.length ? 'Call restore with this backup and planId to go ahead. The current live files are backed up first.' : 'The site already matches this backup.',
       };
     }),
@@ -181,7 +183,8 @@ function createMcp(opts = {}) {
       const out = await tools[name](args || {});
       return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
     } catch (e) {
-      return { content: [{ type: 'text', text: e.message }], isError: true };
+      return { content: [{ type: 'text', text: e.undo ? `${e.message}
+${e.undo} Call preview_restore to see it.` : e.message }], isError: true };
     }
   }
 

package/src/prune.js

@@ -13,6 +13,7 @@
 // → { dryRun, backups, targets, pruned: [{ name, files, bytes }], refused: [{ name, unique }], deleted, bytes }
 const crypto = require('node:crypto');
 const { BACKUP_PREFIX } = require('./diff');
+const { withLock } = require('./lock');
 const { BACKUP_INFO } = require('./backup');
 
 const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
@@ -47,7 +48,12 @@ function chooseTargets(backups, { names, keep }) {
   throw new Error('Say which backups to prune: "names": ["_backup-…"] or "keep": N (newest N stay)');
 }
 
-async function runPrune({ remoteRoot, remoteFs, names, keep, dryRun = false, force = false, onEvent = () => {} }) {
+function runPrune(opts) {
+  if (opts.dryRun) return pruneNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'prune', onEvent: opts.onEvent }, () => pruneNow(opts));
+}
+
+async function pruneNow({ remoteRoot, remoteFs, names, keep, dryRun = false, force = false, onEvent = () => {} }) {
   const root = remoteRoot.replace(/\/$/, '');
   onEvent({ type: 'scan', side: 'remote', dir: root });
   const backups = await listBackups(remoteFs, root);

package/src/queue.js

@@ -36,7 +36,7 @@ function fmtEvent(ev) {
     case 'conflict': return `${t}  CONFLICT ${ev.path}: ${ev.why}`;
     case 'manifest': return `${t}  wrote ${ev.path}`;
     case 'done': return `${t}  done`;
-    case 'error': return `${t}  ERROR ${ev.message}`;
+    case 'error': return `${t}  ERROR ${ev.message}${ev.undo ? ` ${ev.undo}` : ''}`;
     default: return `${t}  ${ev.type}`;
   }
 }

package/src/remote-fs.js

@@ -3,14 +3,34 @@
 //   stat(p) → { size, mtime(ms), isDir } | null
 //   listRecursive(dir, { skipDir }) → [{ path (posix, relative to dir), size, mtime(ms) }]  (files only)
 //   mkdirp(p) · readFile(p) → Buffer · writeFile(p, Buffer) · uploadFile(localPath, p)
-//   rename(a, b) · remove(p) · rmdir(p) · close()
+//   lstat(p) → { isDir, isFile, isLink } | null (does not follow symlinks)
+//   rename(a, b) · replace(tmp, dest) · remove(p) · rmdir(p) · close()
+//
+// Live files are never written in place: the new copy goes to partPath(dest) and replace() swaps it in, so a
+// dropped connection leaves the old file whole, never half a file. The part name keeps the extension (a stray
+// part of config.php is still run as PHP, not served as source) and listRecursive hides part files.
 const posix = require('node:path').posix;
 const fs = require('node:fs');
 const { Client } = require('ssh2');
 
+const PART_PREFIX = '.shipback-part-';
+const LOCK_NAME = '.shipback-lock';
+const partPath = p => posix.join(posix.dirname(p), PART_PREFIX + posix.basename(p));
+const isPart = rel => posix.basename(rel).startsWith(PART_PREFIX);
+const isHidden = rel => isPart(rel) || rel === LOCK_NAME; // Shipback's own working files: never deployed, pulled or listed
+
 // ---------------------------------------------------------------- MemoryRemoteFs (tests)
 class MemoryRemoteFs {
-  constructor() { this.files = new Map(); this.dirs = new Set(['/']); this.failOn = null; }
+  // failOn(p): throw before touching p · tornOn(p): write half of p, then throw (a dropped connection)
+  // odd: path → 'link' | 'fifo', for paths a test says are a symlink or a special file
+  constructor() { this.files = new Map(); this.dirs = new Set(['/']); this.failOn = null; this.tornOn = null; this.odd = new Map(); }
+  async lstat(p) {
+    p = posix.normalize(p);
+    const odd = this.odd.get(p);
+    if (odd) return { isDir: false, isFile: false, isLink: odd === 'link' };
+    const st = await this.stat(p);
+    return st && { isDir: st.isDir, isFile: !st.isDir, isLink: false };
+  }
   _check(p) { if (this.failOn && this.failOn(p)) throw new Error(`Simulated failure on ${p}`); }
   async stat(p) {
     p = posix.normalize(p);
@@ -25,6 +45,7 @@ class MemoryRemoteFs {
       if (!p.startsWith(dir + '/')) continue;
       const rel = p.slice(dir.length + 1);
       if (skipDir && rel.split('/').slice(0, -1).some(seg => skipDir(seg))) continue;
+      if (isHidden(rel)) continue;
       out.push({ path: rel, size: f.data.length, mtime: f.mtime });
     }
     return out.sort((a, b) => a.path.localeCompare(b.path));
@@ -51,10 +72,16 @@ class MemoryRemoteFs {
   async writeFile(p, data) {
     p = posix.normalize(p); this._check(p);
     if (!this.dirs.has(posix.dirname(p))) { const e = new Error(`No such directory: ${posix.dirname(p)}`); e.code = 'ENOENT'; throw e; }
+    if (this.tornOn && this.tornOn(p)) {
+      this.files.set(p, { data: Buffer.from(data).subarray(0, Math.floor(data.length / 2)), mtime: Date.now() });
+      throw new Error(`Simulated connection drop while writing ${p}`);
+    }
     this.files.set(p, { data: Buffer.from(data), mtime: Date.now() });
   }
   async uploadFile(localPath, p) { await this.writeFile(p, await fs.promises.readFile(localPath)); }
   async rename(a, b) { a = posix.normalize(a); b = posix.normalize(b); const f = this.files.get(a); if (!f) throw new Error(`No such file: ${a}`); this.files.delete(a); this.files.set(b, f); }
+  async replace(tmp, dest) { this._check(posix.normalize(dest)); await this.rename(tmp, dest); }
+  async createExclusive(p, data) { p = posix.normalize(p); if (this.files.has(p) || this.dirs.has(p)) return false; await this.writeFile(p, data); return true; }
   async remove(p) { p = posix.normalize(p); this._check(p); if (!this.files.delete(p)) throw new Error(`No such file: ${p}`); }
   async rmdir(p) { this.dirs.delete(posix.normalize(p)); }
   async close() {}
@@ -67,7 +94,26 @@ const UNREACHABLE_HINT = 'Check the port (many shared hosts run SFTP on their ow
   + 'current IP in (some make you allow-list it under SSH Access, and home IPs change).';
 
 class SftpRemoteFs {
-  constructor(client, sftp) { this.client = client; this.sftp = sftp; }
+  constructor(client, sftp) {
+    this.client = client; this.sftp = sftp;
+    // ssh2 drops pending SFTP callbacks when the line goes: without this a cut-off upload never settles and the
+    // CLI exits 0 with nothing said. Every operation fails with this error instead.
+    this.lost = null; this.pending = new Set();
+    const fail = why => {
+      if (this.lost) return;
+      this.lost = new Error(`Lost the connection to the server${why ? ` (${why})` : ''}`);
+      for (const reject of this.pending) reject(this.lost);
+      this.pending.clear();
+    };
+    client.on('close', () => fail()); client.on('error', e => fail(e.message));
+    if (sftp && sftp.on) sftp.on('close', () => fail());
+  }
+  _guard(op) {
+    if (this.lost) return Promise.reject(this.lost);
+    let reject;
+    const cut = new Promise((_, r) => { reject = r; this.pending.add(r); });
+    return Promise.race([op, cut]).finally(() => this.pending.delete(reject));
+  }
 
   /** connect({ host, port, username, password | privateKey, readyTimeout }) */
   static connect(opts) {
@@ -100,10 +146,14 @@ class SftpRemoteFs {
     });
   }
 
-  _p(fn) { return new Promise((res, rej) => fn((err, val) => err ? rej(err) : res(val))); }
+  _p(fn) { return this._guard(new Promise((res, rej) => fn((err, val) => err ? rej(err) : res(val)))); }
 
   async stat(p) {
-    try { const a = await this._p(cb => this.sftp.stat(p, cb)); return { size: a.size, mtime: a.mtime * 1000, isDir: a.isDirectory() }; }
+    try { const a = await this._p(cb => this.sftp.stat(p, cb)); return { size: a.size, mtime: a.mtime * 1000, isDir: a.isDirectory(), mode: a.mode }; }
+    catch (e) { if (e.code === 2 || /No such file/i.test(e.message)) return null; throw e; }
+  }
+  async lstat(p) {
+    try { const a = await this._p(cb => this.sftp.lstat(p, cb)); return { isDir: a.isDirectory(), isFile: a.isFile(), isLink: a.isSymbolicLink() }; }
     catch (e) { if (e.code === 2 || /No such file/i.test(e.message)) return null; throw e; }
   }
   async listRecursive(dir, { skipDir } = {}) {
@@ -114,7 +164,7 @@ class SftpRemoteFs {
         if (e.filename === '.' || e.filename === '..') continue;
         const r = rel ? rel + '/' + e.filename : e.filename;
         if (e.attrs.isDirectory()) { if (!(skipDir && skipDir(e.filename))) await walk(abs + '/' + e.filename, r); }
-        else if (e.attrs.isFile()) out.push({ path: r, size: e.attrs.size, mtime: e.attrs.mtime * 1000 });
+        else if (e.attrs.isFile() && !isHidden(r)) out.push({ path: r, size: e.attrs.size, mtime: e.attrs.mtime * 1000 });
       }
     };
     await walk(dir.replace(/\/$/, ''), '');
@@ -137,25 +187,79 @@ class SftpRemoteFs {
     }
   }
   readFile(p) {
-    return new Promise((resolve, reject) => {
+    return this._guard(new Promise((resolve, reject) => {
       const chunks = [];
       this.sftp.createReadStream(p).on('data', c => chunks.push(c)).on('end', () => resolve(Buffer.concat(chunks))).on('error', reject);
-    });
+    }));
   }
   writeFile(p, data) {
-    return new Promise((resolve, reject) => {
+    return this._guard(new Promise((resolve, reject) => {
       const ws = this.sftp.createWriteStream(p);
       ws.on('error', reject).on('close', resolve);
       ws.end(Buffer.from(data));
-    });
+    }));
   }
   uploadFile(localPath, p) {
     return this._p(cb => this.sftp.fastPut(localPath, p, { concurrency: 4, chunkSize: 32768 }, cb));
   }
   rename(a, b) { return this._p(cb => this.sftp.rename(a, b, cb)); }
+  /** Create p only if nothing is there yet (O_EXCL): true if created, false if it already exists. */
+  async createExclusive(p, data) {
+    let handle;
+    try { handle = await this._p(cb => this.sftp.open(p, 'wx', cb)); }
+    catch (e) { if (await this.stat(p)) return false; throw e; }
+    try { const buf = Buffer.from(data); await this._p(cb => this.sftp.write(handle, buf, 0, buf.length, 0, cb)); }
+    finally { await this._p(cb => this.sftp.close(handle, cb)).catch(() => {}); }
+    return true;
+  }
+  /** Swap a fully written part file in over dest, keeping dest's permissions (suEXEC hosts 500 on 0666 PHP). */
+  async replace(tmp, dest) {
+    const st = await this.stat(dest);
+    if (st && st.mode !== undefined) await this._p(cb => this.sftp.chmod(tmp, st.mode & 0o7777, cb));
+    // OpenSSH (cPanel, Plesk, DirectAdmin, any VPS) has had posix-rename since 2008: one atomic step
+    try { return await this._p(cb => this.sftp.ext_openssh_rename(tmp, dest, cb)); }
+    catch (e) { if (!/does not support/i.test(e.message)) throw e; }
+    if (!st) return this.rename(tmp, dest);
+    try { return await this.rename(tmp, dest); } // some servers replace on a plain rename
+    catch { await this.remove(dest); return this.rename(tmp, dest); } // restore.js copes if the line drops between these two
+  }
   remove(p) { return this._p(cb => this.sftp.unlink(p, cb)); }
   rmdir(p) { return this._p(cb => this.sftp.rmdir(p, cb)); }
   async close() { try { this.client.end(); } catch { /* ignore */ } }
 }
 
-module.exports = { MemoryRemoteFs, SftpRemoteFs };
+/**
+ * Why writing or removing <root>/<rel> would not stay inside the site, or null if it's safe: every folder between
+ * the root and the file must be a real folder (a symlinked one would carry the write somewhere else), and the file
+ * itself a plain file or not there yet. The root itself may be a symlink (cPanel's www → public_html is normal).
+ * folders: a Map shared across one run, so each folder is looked at once.
+ */
+async function outsideReason(remoteFs, root, rel, folders = new Map()) {
+  const segs = rel.split('/');
+  let cur = root.replace(/\/$/, '');
+  for (let i = 0; i < segs.length; i++) {
+    cur += '/' + segs[i];
+    const shown = segs.slice(0, i + 1).join('/');
+    const last = i === segs.length - 1;
+    if (!last && folders.has(cur)) { const why = folders.get(cur); if (why === 'missing') return null; if (why) return why; continue; }
+    const st = await remoteFs.lstat(cur);
+    if (!st) { if (!last) folders.set(cur, 'missing'); return null; } // nothing there yet: what gets made is a real folder
+    let why = null;
+    if (st.isLink) why = `${shown} is a symlink on the server, so writing there could reach outside the site`;
+    else if (!last && !st.isDir) why = `${shown} is not a folder on the server`;
+    else if (last && !st.isFile && !st.isDir) why = `${shown} is a special file on the server (not a plain file)`;
+    if (!last) folders.set(cur, why);
+    if (why) return why;
+  }
+  return null;
+}
+
+/** Write a live file the safe way: to its part file first, then swapped in whole. Give { data } or { localPath }. */
+async function writeLive(remoteFs, dest, { data, localPath }) {
+  const part = partPath(dest);
+  if (localPath !== undefined) await remoteFs.uploadFile(localPath, part);
+  else await remoteFs.writeFile(part, data);
+  await remoteFs.replace(part, dest);
+}
+
+module.exports = { PART_PREFIX, LOCK_NAME, partPath, isPart, isHidden, writeLive, outsideReason, MemoryRemoteFs, SftpRemoteFs };

package/src/restore.js

@@ -5,6 +5,9 @@
 // .backup.json saying which files it added and what it uploaded (sha256). Restore:
 //   · checks first that each live file is still what that run left there (or is already the old copy).
 //     A file edited on the server since is a conflict, and then nothing is changed unless { force: true }
+//   · checks each saved copy against the sha256 recorded when it was saved: a damaged copy is never put back
+//   · copes with a run that stopped part way: files it never reached are already right, and a file caught
+//     between "old removed" and "new swapped in" (servers without posix-rename) is found in its part file
 //   · backs up everything it is about to change into a new _backup-<stamp>/ with its own .backup.json,
 //     so a restore can itself be restored
 //   · writes each backed-up file back to its live path and removes the files that run added
@@ -20,6 +23,8 @@ const posix = require('node:path').posix;
 const { BACKUP_PREFIX, MANIFEST_NAME } = require('./diff');
 const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, BACKUP_INFO } = require('./backup');
 const { listBackups } = require('./prune');
+const { partPath, writeLive, outsideReason } = require('./remote-fs');
+const { withLock } = require('./lock');
 
 const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
 
@@ -39,37 +44,73 @@ async function describeBackups({ remoteRoot, remoteFs }) {
     const info = await readBackupInfo(remoteFs, `${root}/${name}`);
     const files = (await remoteFs.listRecursive(`${root}/${name}`)).filter(f => f.path !== BACKUP_INFO).length;
     out.push(info
-      ? { name, action: info.action, at: info.at, from: info.from, overwritten: info.overwritten.length, added: info.added.length, deleted: info.deleted.length, files, legacy: false }
+      ? { name, action: info.action, at: info.at, from: info.from, overwritten: info.overwritten.length, added: info.added.length, deleted: info.deleted.length, files, legacy: false, status: info.status }
       : { name, files, legacy: true });
   }
   return out;
 }
 
-async function runRestore({ remoteRoot, remoteFs, name, dryRun = false, force = false, now = new Date(), onEvent = () => {} }) {
+function runRestore(opts) {
+  if (opts.dryRun) return restoreNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'restore', onEvent: opts.onEvent }, () => restoreNow(opts));
+}
+
+async function restoreNow({ remoteRoot, remoteFs, name, dryRun = false, force = false, now = new Date(), onEvent = () => {} }) {
   const root = remoteRoot.replace(/\/$/, '');
   onEvent({ type: 'scan', side: 'remote', dir: root });
-  const target = chooseBackup(await listBackups(remoteFs, root), name);
+  let target = chooseBackup(await listBackups(remoteFs, root), name);
+  let info = await readBackupInfo(remoteFs, `${root}/${target}`);
+  let resumed = null;
+  // the latest run is a restore that was cut off: running it again finishes that restore
+  const latest = name === undefined || name === null || name === '' || name === 'latest';
+  if (latest && info && info.action === 'restore' && info.status && info.from) {
+    resumed = target; target = chooseBackup(await listBackups(remoteFs, root), info.from);
+    info = await readBackupInfo(remoteFs, `${root}/${target}`);
+  }
   const dir = `${root}/${target}`;
-  const info = await readBackupInfo(remoteFs, dir);
-  const summary = { dryRun, backup: target, action: info ? info.action : undefined, legacy: !info, put: [], remove: [], same: [], conflicts: [], refused: false, undoBackupDir: null };
+  const summary = { dryRun, backup: target, action: info ? info.action : undefined, legacy: !info, resumed, stoppedEarly: false, put: [], remove: [], same: [], conflicts: [], refused: false, undoBackupDir: null };
+  if (info && info.status === 'saving') {
+    // that run was cut off while it was still making its backup copies, before it changed a single live file
+    summary.stoppedEarly = true;
+    onEvent({ type: 'restore-plan', backup: target, put: [], remove: [], same: 0, conflicts: 0, legacy: false, stoppedEarly: true });
+    onEvent({ type: 'done', summary });
+    return summary;
+  }
 
   const left = new Map();      // path → sha256 the run left there (overwritten + added)
   const deleted = new Set();   // paths the run deleted
+  const was = new Map();       // path → sha256 of the copy saved in the backup folder (records from 0.2 on)
   if (info) {
     for (const e of [...info.overwritten, ...info.added]) left.set(e.path, e.sha256);
     for (const e of info.deleted) deleted.add(e.path);
+    for (const e of [...info.overwritten, ...info.deleted]) if (e.was) was.set(e.path, e.was);
   }
   const live = async p => {
     const st = await remoteFs.stat(`${root}/${p}`);
-    if (!st) return null;
+    if (!st) {
+      // the line dropped mid-swap: the run's whole copy is still in the part file
+      const part = partPath(`${root}/${p}`);
+      if (left.has(p) && await remoteFs.stat(part) && sha256(await remoteFs.readFile(part)) === left.get(p)) return left.get(p);
+      return null;
+    }
     return st.isDir ? 'dir' : sha256(await remoteFs.readFile(`${root}/${p}`));
   };
   const conflict = (p, why) => summary.conflicts.push({ path: p, why });
 
+  // never through a symlink or over a special file, even forced: that could reach outside the site
+  const folders = new Map(), unsafe = new Set();
+  const outside = async p => {
+    const why = await outsideReason(remoteFs, root, p, folders);
+    if (why) { unsafe.add(p); conflict(p, why); }
+    return !!why;
+  };
+
   // 1. what goes back: every file in the backup folder
   const puts = [];
   for (const f of (await remoteFs.listRecursive(dir)).filter(f => f.path !== BACKUP_INFO)) {
+    if (await outside(f.path)) continue;
     const data = await remoteFs.readFile(`${dir}/${f.path}`);
+    if (was.has(f.path) && sha256(data) !== was.get(f.path)) { conflict(f.path, 'its copy in the backup folder is damaged (it no longer matches what was saved)'); continue; } // never put back, even forced
     const now_ = await live(f.path);
     if (now_ === sha256(data)) { summary.same.push(f.path); continue; }
     if (now_ === 'dir') { conflict(f.path, 'is a folder on the server now'); continue; } // can't write a file over it, even forced
@@ -80,6 +121,7 @@ async function runRestore({ remoteRoot, remoteFs, name, dryRun = false, force =
   // 2. what comes off: the files that run added
   const removes = [];
   if (info) for (const e of info.added) {
+    if (await outside(e.path)) continue;
     const now_ = await live(e.path);
     if (now_ === null) { summary.same.push(e.path); continue; }
     if (now_ === 'dir') { conflict(e.path, 'is a folder on the server now'); continue; }
@@ -97,45 +139,66 @@ async function runRestore({ remoteRoot, remoteFs, name, dryRun = false, force =
     onEvent({ type: 'done', summary });
     return summary;
   }
-  if (dryRun || (!puts.length && !removes.length)) { onEvent({ type: 'done', summary }); return summary; }
-
-  // 3. back up what is live now, so this restore can be undone too
-  const undoDir = await freeBackupDir(remoteFs, root, makeStamp(now));
-  const res = await backupFiles({ remoteFs, root, paths: [...summary.put, ...summary.remove], backupDir: undoDir, onEvent });
-  const copied = new Set(res.copied);
-  await writeBackupInfo({ remoteFs, backupDir: undoDir, info: {
-    action: 'restore', from: target, at: now.toISOString(),
-    overwritten: puts.filter(p => copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data) })),
-    added: puts.filter(p => !copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data) })),
-    deleted: removes.filter(p => copied.has(p)).map(p => ({ path: p })),
-  } });
-  summary.undoBackupDir = undoDir;
+  // part files a stopped run left behind (hidden from listings, but they hold the run's bytes)
+  const sweepParts = async () => {
+    for (const p of new Set([...left.keys(), ...deleted])) {
+      if (unsafe.has(p)) continue;
+      const part = partPath(`${root}/${p}`);
+      if (await remoteFs.stat(part)) await remoteFs.remove(part).catch(() => {});
+    }
+  };
+  if (dryRun) { onEvent({ type: 'done', summary }); return summary; }
+  if (!puts.length && !removes.length) { await sweepParts(); onEvent({ type: 'done', summary }); return summary; }
+  try {
+    // 3. back up what is live now, so this restore can be undone too. Its record says 'saving', then 'running'
+    //    while files are written, then nothing: cut off part way, running restore again finishes the job.
+    const undoDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+    summary.undoBackupDir = undoDir;
+    const head = { action: 'restore', from: target, at: now.toISOString() };
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: { ...head, status: 'saving', overwritten: [], added: [], deleted: [] } });
+    const res = await backupFiles({ remoteFs, root, paths: [...summary.put, ...summary.remove], backupDir: undoDir, onEvent });
+    const copied = new Set(res.copied);
+    const record = {
+      ...head,
+      overwritten: puts.filter(p => copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data), was: res.was.get(p.path) })),
+      added: puts.filter(p => !copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data) })),
+      deleted: removes.filter(p => copied.has(p)).map(p => ({ path: p, was: res.was.get(p) })),
+    };
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: { ...record, status: 'running' } });
 
-  // 4. put the old copies back, take the added files off
-  const madeDirs = new Set();
-  for (const p of puts) {
-    const dest = `${root}/${p.path}`;
-    const d = posix.dirname(dest);
-    if (!madeDirs.has(d)) { await remoteFs.mkdirp(d); madeDirs.add(d); }
-    await remoteFs.writeFile(dest, p.data);
-    onEvent({ type: 'restore', path: p.path, bytes: p.data.length });
-  }
-  for (const p of removes) { await remoteFs.remove(`${root}/${p}`); onEvent({ type: 'delete', path: p }); }
-  // folders the deploy made just for added files go too, once empty
-  for (const d of [...new Set(removes.map(p => posix.dirname(p)).filter(d => d !== '.'))].sort((a, b) => b.length - a.length)) {
-    for (let cur = d; cur !== '.'; cur = posix.dirname(cur)) {
-      const abs = `${root}/${cur}`;
-      if (!(await remoteFs.stat(abs)) || (await remoteFs.listDir(abs)).length) break;
-      await remoteFs.rmdir(abs);
+    // 4. put the old copies back, take the added files off
+    const madeDirs = new Set();
+    for (const p of puts) {
+      const dest = `${root}/${p.path}`;
+      const d = posix.dirname(dest);
+      if (!madeDirs.has(d)) { await remoteFs.mkdirp(d); madeDirs.add(d); }
+      await writeLive(remoteFs, dest, { data: p.data });
+      onEvent({ type: 'restore', path: p.path, bytes: p.data.length });
+    }
+    for (const p of removes) { await remoteFs.remove(`${root}/${p}`); onEvent({ type: 'delete', path: p }); }
+    // folders the deploy made just for added files go too, once empty
+    for (const d of [...new Set(removes.map(p => posix.dirname(p)).filter(d => d !== '.'))].sort((a, b) => b.length - a.length)) {
+      for (let cur = d; cur !== '.'; cur = posix.dirname(cur)) {
+        const abs = `${root}/${cur}`;
+        if (!(await remoteFs.stat(abs)) || (await remoteFs.listDir(abs)).length) break;
+        await remoteFs.rmdir(abs);
+      }
     }
-  }
 
-  // 5. the manifest no longer describes these paths
-  try {
-    const m = JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8'));
-    for (const p of [...summary.put, ...summary.remove]) delete m.files[p];
-    await remoteFs.writeFile(`${root}/${MANIFEST_NAME}`, JSON.stringify(m, null, 1));
-  } catch { /* no manifest: nothing to correct */ }
+    await sweepParts();
+
+    // 5. the manifest no longer describes these paths
+    try {
+      const m = JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8'));
+      for (const p of [...summary.put, ...summary.remove]) delete m.files[p];
+      await remoteFs.writeFile(`${root}/${MANIFEST_NAME}`, JSON.stringify(m, null, 1));
+    } catch { /* no manifest: nothing to correct */ }
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: record });
+  } catch (err) {
+    err.undo = 'The restore stopped part way. Run the same restore again: it finishes the job.';
+    onEvent({ type: 'error', message: err.message, undo: err.undo, summary });
+    throw err;
+  }
 
   onEvent({ type: 'done', summary });
   return summary;

package/src/server.js

@@ -68,6 +68,15 @@ async function createApp(opts = {}) {
     for (const l of job.listeners) l(ev);
     if (ev.type === 'done' || ev.type === 'error') job.done = true;
   }
+  // Runs a UI job, holding back its last event ('done' / 'error') until the history line is written:
+  // the UI reloads history on 'done', so the run has to be on file by then.
+  function track(job, run, rec) {
+    let last = null;
+    const onEvent = ev => { if (ev.type === 'done' || ev.type === 'error') last = ev; else emit(job, ev); };
+    return run(onEvent)
+      .then(summary => rec(summary), err => rec(last && last.summary, err))
+      .finally(() => { if (last) emit(job, last); });
+  }
 
   async function getSite(name) {
     const { sites } = await loadSites(sitesFile);
@@ -125,9 +134,9 @@ async function createApp(opts = {}) {
       const job = newJob('deploy');
       const args = { localDir: body.localDir || site.localDir, remoteRoot: body.remoteDir || site.remoteRoot };
       const startedAt = new Date().toISOString();
-      runDeploy({ ...args, remoteFs: rfs, dryRun: !!body.dryRun, backup: body.backup !== false, mirror: !!body.mirror, ignore: site.ignore, now: now(), onEvent: ev => emit(job, ev) })
-        .then(summary => { if (!summary.dryRun) record({ action: 'deploy', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary }); },
-              err => record({ action: 'deploy', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary: job.events.find(e => e.type === 'error')?.summary, error: err.message }))
+      track(job, onEvent => runDeploy({ ...args, remoteFs: rfs, dryRun: !!body.dryRun, backup: body.backup !== false, mirror: !!body.mirror, ignore: site.ignore, now: now(), onEvent }),
+        (summary, err) => err ? record({ action: 'deploy', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary, error: err.message })
+          : !summary.dryRun && record({ action: 'deploy', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary }))
         .finally(() => rfs.close());
       return { jobId: job.id };
     },
@@ -139,9 +148,9 @@ async function createApp(opts = {}) {
       const args = { localDir: body.localDir || site.localDir, remoteRoot: body.remoteDir || site.remoteRoot };
       if (!args.localDir) throw new HttpError(400, 'No local folder given');
       const startedAt = new Date().toISOString();
-      runPull({ ...args, remoteFs: rfs, dryRun: !!body.dryRun, backup: body.backup !== false, mirror: !!body.mirror, ignore: site.ignore, now: now(), onEvent: ev => emit(job, ev) })
-        .then(summary => { if (!summary.dryRun) record({ action: 'pull', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary }); },
-              err => record({ action: 'pull', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, error: err.message }))
+      track(job, onEvent => runPull({ ...args, remoteFs: rfs, dryRun: !!body.dryRun, backup: body.backup !== false, mirror: !!body.mirror, ignore: site.ignore, now: now(), onEvent }),
+        (summary, err) => err ? record({ action: 'pull', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, error: err.message })
+          : !summary.dryRun && record({ action: 'pull', site: site.name, trigger: 'ui', localDir: args.localDir, remoteDir: args.remoteRoot, startedAt, summary }))
         .finally(() => rfs.close());
       return { jobId: job.id };
     },
@@ -165,9 +174,8 @@ async function createApp(opts = {}) {
       const rfs = await connectSite(site);
       const job = newJob('upload');
       const startedAt = new Date().toISOString();
-      uploadFiles({ files, remoteDir, remoteFs: rfs, backup: form.get('backup') !== 'false', now: now(), onEvent: ev => emit(job, ev) })
-        .then(summary => record({ action: 'upload', site: site.name, trigger: 'ui', remoteDir, startedAt, summary }),
-              err => record({ action: 'upload', site: site.name, trigger: 'ui', remoteDir, startedAt, error: err.message }))
+      track(job, onEvent => uploadFiles({ files, remoteDir, remoteFs: rfs, backup: form.get('backup') !== 'false', now: now(), onEvent }),
+        (summary, err) => record({ action: 'upload', site: site.name, trigger: 'ui', remoteDir, startedAt, ...(err ? { error: err.message } : { summary }) }))
         .finally(async () => { await rfs.close(); await fs.rm(tmp, { recursive: true, force: true }); });
       return { jobId: job.id, files: files.map(f => f.name) };
     },