Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix(backup): restore a pre-split snapshot's CoS settings over a newer config.json

Adam Eivy43a9ac277244
diff --git a/docs/BACKUP.md b/docs/BACKUP.md
index 5354bcfcd2..f70d48a7f5 100644
--- a/docs/BACKUP.md
+++ b/docs/BACKUP.md
@@ -507,6 +507,8 @@ Snapshots from PortOS versions that predate `manifest.json` remain restorable as
After the preflight, rsync copies `<snapshot>/data/` back to `./data/`. Restore always passes `--checksum`, so rsync compares file contents even when the live file has the same size and modification time as the snapshot; equal-content files remain skippable, while differing bytes appear in previews and are restored. This applies to dry-run and live restores, including selective subdirectory restores and legacy snapshots without a manifest. `dryRun: true` (the default) reports what would change without writing; an optional `subdirFilter` limits the restore to one subdirectory.
+File restore copies what the snapshot holds and leaves live files the snapshot lacks in place. One consequence is handled explicitly: a snapshot taken before the CoS config moved to its own file (#6182) carries its CoS settings inside `cos/state.json` and has no `cos/config.json`. When such a restore lands that legacy slice, the live `cos/config.json` (newer than the restore point) is moved aside to `cos/config.pre-restore-<timestamp>.json` and the settings are recovered from the restored `state.json`; otherwise the newer file would keep winning every read.
+
**Every nonzero rsync exit fails a restore, including 24.** A backup tolerates exit 24 ("some source files vanished") because it reads the live data tree, where a file deleted mid-scan is normal. A restore reads a snapshot that must not change under it, so a vanished source file means live data may now mix restored and older files: preview and execution both reject it. An execution failure is reported as a partial restore — the error says some files may already have been overwritten because file restore is not transactional — and caches (settings, Brain, media index) are reconciled before the error is returned, exactly as for any other failed transfer.
#### Database authority is not restored
diff --git a/server/services/backup.js b/server/services/backup.js
index 55f37aadcf..08b4bd4cce 100644
--- a/server/services/backup.js
+++ b/server/services/backup.js
@@ -1748,7 +1748,7 @@ async function restoreHeldSnapshot({ snapshotDir, currentSource }, snapshotId, {
}
const scope = subdirFilter;
- const changedFiles = await withLiveFileRestoreOwners(scope, () => transferAndReconcileLiveFiles({
+ const changedFiles = await withLiveFileRestoreOwners(scope, srcDir, () => transferAndReconcileLiveFiles({
subdirFilter,
transfer: () => transferWithIdentityFence({ scope, srcDir, transferFiles }),
}));
@@ -1762,7 +1762,8 @@ const COS_RESTORE_SCOPES = ['cos', 'cos/config.json', 'cos/state.json', 'cos/age
* acquisition order, and each owner is released in reverse after everything
* inside it (transfer plus partial-failure reconciliation) has settled.
* `appliesTo` receives the normalized scope (`''`/undefined = full restore);
- * `hold` acquires the owner, runs `inner`, and releases on every exit. Domain
+ * `hold(inner, { srcDir })` acquires the owner, runs `inner`, and releases on
+ * every exit; `srcDir` is the verified snapshot's data directory. Domain
* modules are imported only once every outer owner is held.
*
* - The snapshot cut drains in-flight asset publications BEFORE any domain
@@ -1806,9 +1807,14 @@ const LIVE_FILE_RESTORE_OWNERS = Object.freeze([
{
name: 'CoS config and runtime',
appliesTo: scope => !scope || COS_RESTORE_SCOPES.includes(scope) || scope.startsWith('cos/agents/'),
- hold: async (inner) => {
+ hold: async (inner, { srcDir }) => {
+ // A pre-split snapshot (#6182) has no config.json; its config is in state.json.
+ const snapshotCarriesConfig = await stat(join(srcDir, 'cos', 'config.json')).then(
+ info => info.isFile(),
+ error => { if (error.code === 'ENOENT') return false; throw error; },
+ );
const { withLiveCosRestore } = await import('./cosState.js');
- return withLiveCosRestore(inner);
+ return withLiveCosRestore(inner, { snapshotCarriesConfig });
},
},
{
@@ -1830,9 +1836,9 @@ const LIVE_FILE_RESTORE_OWNERS = Object.freeze([
]);
/** Run `operation` inside every live-restore owner that applies to `scope`, in table order. */
-function withLiveFileRestoreOwners(scope, operation) {
+function withLiveFileRestoreOwners(scope, srcDir, operation) {
const nested = LIVE_FILE_RESTORE_OWNERS.reduceRight(
- (inner, owner) => (owner.appliesTo(scope) ? () => owner.hold(inner) : inner),
+ (inner, owner) => (owner.appliesTo(scope) ? () => owner.hold(inner, { srcDir }) : inner),
operation,
);
return nested();
diff --git a/server/services/backup.test.js b/server/services/backup.test.js
index 6f356eb719..3643c3a0de 100644
--- a/server/services/backup.test.js
+++ b/server/services/backup.test.js
@@ -3428,6 +3428,8 @@ describe('restoreSnapshot snapshotId, filter flags, and settings re-sync', () =>
it.each([undefined, 'cos', 'cos/', 'cos/config.json', 'cos/state.json', 'cos/agents', 'cos/agents/', 'cos/agents/index.json'])('holds the boundary for affected live scope %s', async subdirFilter => {
await runRestore('/dest', 'snap-1', { dryRun: false, subdirFilter });
expect(withLiveCosRestore).toHaveBeenCalledTimes(1);
+ // This snapshot has no cos/config.json, like one taken before the #6182 split.
+ expect(withLiveCosRestore).toHaveBeenCalledWith(expect.any(Function), { snapshotCarriesConfig: false });
});
it.each([{ dryRun: true }, { dryRun: false, subdirFilter: 'images' }, { dryRun: true, subdirFilter: 'cos/agents' }])('leaves unaffected scope alone: %j', async options => {
await runRestore('/dest', 'snap-1', options);
diff --git a/server/services/cosState.js b/server/services/cosState.js
index 5a57e505af..e423b706e4 100644
--- a/server/services/cosState.js
+++ b/server/services/cosState.js
@@ -550,13 +550,36 @@ export async function saveState(state) {
stateCache = stampGeneration(state, stateRecovery);
}
+const legacyConfigSlice = (state) => (isPlainObject(state?.config) ? JSON.stringify(state.config) : null);
+
+/**
+ * A snapshot taken before the #6182 split keeps the CoS config inside
+ * state.json and carries no config.json. Restored over an upgraded install, the
+ * live config.json is newer than the snapshot yet wins every read (and migration
+ * 339 no-ops on its presence), so the restored settings were silently discarded
+ * and then stripped by the next saveState. When the transfer lands a legacy
+ * slice the live state.json did not already hold, move config.json aside — kept
+ * for manual recovery, never deleted — so readConfig() completes the split from
+ * the restored slice.
+ */
+async function supersedeConfigForRestoredLegacySlice(sliceBefore) {
+ if (!existsSync(STATE_FILE) || !existsSync(CONFIG_FILE)) return;
+ const restored = legacyConfigSlice(parseStateFile(await readFile(STATE_FILE, 'utf-8'), 'CoS state (restored legacy config)'));
+ if (restored === null || restored === sliceBefore) return;
+ const parked = join(dirname(CONFIG_FILE), `config.pre-restore-${new Date().toISOString().replace(/[:.]/g, '-')}.json`);
+ await rename(CONFIG_FILE, parked);
+ console.log(`📦 Restored snapshot predates config.json; moved the newer CoS config aside to ${basename(parked)} and recovering settings from the restored state.json`);
+}
+
/**
* Drain config, then runtime mutations and keep both queues until transfer and
* reload settle. This order matches config changes that consult runtime state;
* never acquire the config queue from inside the state queue.
* Callers must read their mutation's pre-image INSIDE its respective queue.
+ * `snapshotCarriesConfig: false` marks a snapshot without config.json (see
+ * supersedeConfigForRestoredLegacySlice).
*/
-export function withLiveCosRestore(transfer) {
+export function withLiveCosRestore(transfer, { snapshotCarriesConfig = true } = {}) {
return withConfigLock(() => withStateLock(async () => {
const persisted = await readStateForSafetyCheck();
const states = [stateCache, persisted.state].filter(Boolean);
@@ -571,11 +594,14 @@ export function withLiveCosRestore(transfer) {
});
}
+ const sliceBefore = legacyConfigSlice(persisted.state);
const [result] = await Promise.allSettled([Promise.resolve().then(transfer)]);
restoreGeneration += 1;
configCache = null;
stateCache = null;
const [reload] = await Promise.allSettled([(async () => {
+ // Also after a partial transfer: a restored slice is the snapshot's config.
+ if (!snapshotCarriesConfig) await supersedeConfigForRestoredLegacySlice(sliceBefore);
const { reloadAgentIndexAfterRestore } = await import('./cosAgentIndex.js');
await reloadAgentIndexAfterRestore();
const state = await loadState();
diff --git a/server/services/cosState.test.js b/server/services/cosState.test.js
index 74d0f8021c..be91872d59 100644
--- a/server/services/cosState.test.js
+++ b/server/services/cosState.test.js
@@ -415,6 +415,27 @@ describe('live CoS restore boundary', () => {
expect(readJson(CONFIG_PATH).persistentMindPrompt.instructions).toBe('Partial restore');
});
+ // A pre-#6182 snapshot keeps its config in state.json and ships no
+ // config.json, so the live config.json is newer than the restore point.
+ it.each([
+ { snapshotCarriesConfig: false, restoredConfig: null, expected: 7, parked: true },
+ { snapshotCarriesConfig: true, restoredConfig: { maxConcurrentAgents: 5 }, expected: 5, parked: false },
+ ])('restores the snapshot config over a newer config.json: %j', async ({ snapshotCarriesConfig, restoredConfig, expected, parked }) => {
+ writeConfig({ maxConcurrentAgents: 3 });
+ writeState({ agents: {} });
+ const store = await freshModule();
+ await store.loadState();
+ await store.withLiveCosRestore(async () => {
+ if (restoredConfig) writeConfig(restoredConfig);
+ writeState({ agents: {}, config: { maxConcurrentAgents: 7 } });
+ }, { snapshotCarriesConfig });
+ expect((await store.getConfig()).maxConcurrentAgents).toBe(expected);
+ expect(readJson(CONFIG_PATH).maxConcurrentAgents).toBe(expected);
+ const aside = readdirSync(COS_DIR).filter(f => f.startsWith('config.pre-restore-'));
+ expect(aside).toHaveLength(parked ? 1 : 0);
+ if (parked) expect(readJson(join(COS_DIR, aside[0]))).toEqual({ maxConcurrentAgents: 3 });
+ });
+
it.each([
{ running: true, agents: {} },
{ agents: { example: { status: 'running' } } },