refactor(runtime-host)!: make the Runtime Host State Root self-contained

.github/workflows/cli-package-validation.yml

@@ -29,21 +29,26 @@ on:
       - 'package-lock.json'
       - 'packages/cli/RUNTIME_HOST_PEER_*'
       - 'packages/cli/src/cli-core.ts'
-      - 'packages/cli/src/runtime-host-cli.ts'
-      - 'packages/cli/src/runtime-host-package-deployment.ts'
-      - 'packages/cli/src/runtime-host-peer-*'
-      - 'packages/cli/src/runtime-host-service-*'
-      - 'packages/cli/src/runtime-host-windows-*'
+      - 'packages/cli/src/runtime-host-**'
       - 'packages/runtime-host/package.json'
-      - 'packages/runtime-host/src/client/peer-client.ts'
+      - 'packages/runtime-host/src/root-upgrade.ts'
+      - 'packages/runtime-host/src/client/**'
+      - 'packages/runtime-host/src/operator/**'
       - 'packages/runtime-host/src/peer-mesh/**'
-      - 'packages/runtime-host/src/server/peer-listener.ts'
-      - 'packages/runtime-host/src/transport/peer-native.ts'
+      - 'packages/runtime-host/src/server/**'
+      - 'packages/runtime-host/src/transport/**'
       - 'packages/storage/package.json'
+      - 'packages/storage/src/artifact-writer-bootstrap-lock.ts'
       - 'packages/storage/src/file-lifetime-owner.ts'
+      - 'packages/storage/src/marker-file.ts'
       - 'packages/storage/src/native-file-lock.ts'
+      - 'packages/storage/src/process-lifetime-file-update-lock.ts'
+      - 'packages/storage/src/root-authority.ts'
+      - 'packages/storage/src/stable-storage.ts'
+      - 'packages/storage/src/usage-stores.ts'
       - 'scripts/generate-runtime-host-peer-*'
       - 'scripts/release-cli-package.mjs'
+      - 'scripts/release-cli-runtime-host-diagnostics.mjs'
       - 'scripts/qualify-released-cli-state-root.mjs'
       - 'scripts/qualify-released-cli-state-root.test.mjs'
       - 'scripts/released-cli-state-root-fixture.mjs'

.github/workflows/windows-recovery.yml

@@ -66,9 +66,20 @@ on:
       # `scripts/windows-package-source-closure.test.mjs` recomputes this set
       # from the dist tests the steps run and fails on any difference in either
       # direction.
+      - 'packages/cli/src/__tests__/runtime-host-root-upgrade.test.ts'
+      - 'packages/cli/src/runtime-host-cli-installation.ts'
+      - 'packages/cli/src/runtime-host-lifecycle-transaction.ts'
+      - 'packages/cli/src/runtime-host-managed-deployment.ts'
+      - 'packages/cli/src/runtime-host-package-deployment.ts'
+      - 'packages/cli/src/runtime-host-peer-artifact.ts'
+      - 'packages/cli/src/runtime-host-service-management-command.ts'
+      - 'packages/cli/src/runtime-host-setup-command.ts'
+      - 'packages/cli/src/runtime-host-update-command.ts'
+      - 'packages/cli/src/runtime-host-windows-task-launcher-artifact.ts'
       - 'packages/core/src/diagnostic-log.ts'
       - 'packages/runtime-host/src/__tests__/control-endpoint.test.ts'
       - 'packages/runtime-host/src/__tests__/fixtures/endpoint-hygiene.ts'
+      - 'packages/runtime-host/src/__tests__/root-upgrade.test.ts'
       - 'packages/runtime-host/src/__tests__/skill-catalog-protocol.test.ts'
       - 'packages/runtime-host/src/__tests__/skill-catalog-repository.test.ts'
       - 'packages/runtime-host/src/__tests__/skill-catalog-transaction.test.ts'
@@ -90,6 +101,7 @@ on:
       - 'packages/runtime-host/src/peer-reachability/publisher.ts'
       - 'packages/runtime-host/src/protocol/host-status.ts'
       - 'packages/runtime-host/src/protocol/skill-catalog.ts'
+      - 'packages/runtime-host/src/root-upgrade.ts'
       - 'packages/runtime-host/src/server/access-credential-store.ts'
       - 'packages/runtime-host/src/server/host-resource-probe.ts'
       - 'packages/runtime-host/src/server/skill-catalog-repository.ts'
@@ -129,6 +141,7 @@ on:
       - 'packages/storage/src/session-bundle-file-service.ts'
       - 'packages/storage/src/sqlite-long-term-memory-store.ts'
       - 'packages/storage/src/stable-storage.ts'
+      - 'packages/storage/src/workspace-root.ts'
       - '.github/workflows/windows-recovery.yml'
   # Unfiltered on purpose: required_status_checks is `strict: false`, so a pull
   # request goes green against a stale base and only the merged result proves
@@ -248,6 +261,14 @@ jobs:
             packages/runtime/dist/__tests__/runtime-resume-crash.test.js `
             packages/runtime/dist/__tests__/runtime-continuation-crash.test.js
 
+      - name: Verify Runtime Host root format upgrade
+        shell: pwsh
+        run: |
+          node.exe --test --test-concurrency=1 `
+            packages/storage/dist/__tests__/root-migration.test.js `
+            packages/runtime-host/dist/__tests__/root-upgrade.test.js `
+            packages/cli/dist/__tests__/runtime-host-root-upgrade.test.js
+
       - name: Verify Runtime Host owner-death recovery
         shell: pwsh
         run: |

CHANGELOG.md

@@ -53,6 +53,17 @@
   persisted, and a transcript that opens on an assistant reply keeps that turn.
 - Reading a Claude Code transcript for the Session catalog is bounded to a head
   and tail window instead of reading each transcript to its end.
+- Made the Runtime Host State Root self-contained. The root marker is now schema version 2:
+  owner election, the Artifact-writer lock, Host registrations, startup diagnostics, plugin data
+  and credentials, and the managed deployment record all live under `<root>/.maka-host` instead of
+  the account's cache and data directories. Roots written by `v0.1.x`, `cli-v0.1.0-beta.1`,
+  `v0.2.0-incubating-rc1`, or `v0.2.0-dev` builds carry schema version 1 and migrate automatically
+  the first time a Runtime Host startup, activation, update, or service recovery resolves them;
+  an interrupted migration resumes forward on the next attempt and needs no manual repair.
+  **Earlier releases cannot open a migrated root** — downgrading requires restoring a pre-upgrade
+  copy of the root directory. Schema version 1 support is limited to the 0.2.x line: starting with
+  0.3, Maka rejects unmigrated roots, so a root that skips every 0.2.x release must be opened once
+  by a 0.2.x build or recovered from backup.
 - Made typed `request()` the sole direct Runtime Host operation API; removed the 17 forwarding
   aliases from direct and reconnecting connections while preserving status validation,
   subscriptions, capabilities, listeners, lifecycle, and close behavior.

apps/desktop/src/main/__tests__/runtime-host-local-operator.test.ts

@@ -38,6 +38,7 @@ import {
   createDesktopRuntimeHostLocalOperator,
   runtimeHostLocalSetupCommand,
 } from '../runtime-host-local-operator.js';
+import { createDesktopRuntimeHostLocalManagement } from '../runtime-host-local-management.js';
 
 const OPERATOR = {
   kind: 'node' as const,
@@ -386,6 +387,24 @@ test('local update runs the selected package against the exact managed deploymen
   );
   assert.deepEqual(phases, ['staging']);
 
+  const settings = createDesktopRuntimeHostLocalManagement({
+    remoteAccess: {
+      changeManaged: async (operation) => operation({
+        serviceId: 'a'.repeat(64), rootPath: '/tmp/maka/root', rootId: 'a'.repeat(64),
+        deploymentId, operator: OPERATOR,
+      }),
+    } as Parameters<typeof createDesktopRuntimeHostLocalManagement>[0]['remoteAccess'],
+    operator,
+    rootPath: '/tmp/maka/root',
+    resolveUpdatePackage: () => ({ kind: 'npm', specifier: 'maka-agent@0.3.0' }),
+    currentHostEpoch: () => undefined,
+    awaitUpdatedConnection: async () => {},
+  });
+  await settings.update(false, () => {});
+  assert.ok(operatorArgs()?.includes('--allow-manual-update'));
+  assert.ok(!operatorArgs()?.includes('--expected-host-json'));
+  assert.ok(!operatorArgs()?.includes('--allow-interrupt-active-tasks'));
+
   const developmentIntegrity = `sha512-${Buffer.alloc(64, 9).toString('base64')}`;
   await operator.runUpdate(
     {

apps/desktop/src/main/__tests__/runtime-host-local-remote-access.test.ts

@@ -20,13 +20,20 @@
 import assert from 'node:assert/strict';
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import os from 'node:os';
+import { syncBuiltinESMExports } from 'node:module';
 import { join } from 'node:path';
 import test from 'node:test';
-import { decodeRuntimeHostOwnerConnectionCode } from '@maka/runtime-host/client';
+import { decodeRuntimeHostOwnerConnectionCode, connectOrSpawnRuntimeHost, runtimeHostStartupError } from '@maka/runtime-host/client';
+import { resolveStorageRootIdentity, STORAGE_ROOT_MARKER_FILE } from '@maka/storage/root-authority';
+import { resolveRuntimeHostManagedDeploymentAuthorityRoot } from '@maka/runtime-host/operator';
+import { resolveDesktopStorageRoot } from '../storage-root-startup.js';
+import { canRepairManagedRuntimeHostStartup } from '../runtime-host-startup-recovery.js';
 import {
   INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
   RUNTIME_HOST_COMPATIBILITY_EPOCH,
   RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION,
+  RUNTIME_HOST_PROTOCOL_VERSION,
   type HostRegistration,
 } from '@maka/runtime-host/protocol';
 import type { RuntimeHostDesktopManager } from '../runtime-host-desktop-manager.js';
@@ -329,8 +336,27 @@ test('repairs an existing managed Host with the current setup package and restar
   const base = await mkdtemp(join(tmpdir(), 'maka-local-managed-repair-'));
   t.after(() => rm(base, { recursive: true, force: true }));
   const clientDataRoot = join(base, 'client');
-  const rootPath = join(clientDataRoot, 'workspaces', 'default');
-  const rootId = 'a'.repeat(64);
+  const identity = await resolveStorageRootIdentity({ path: join(clientDataRoot, 'workspaces', 'default'), kind: 'interactive' });
+  const rootPath = identity.canonicalPath;
+  const rootId = identity.rootId;
+  const account = os.userInfo();
+  t.mock.method(os, 'userInfo', () => ({ ...account, homedir: base }));
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  const markerPath = join(rootPath, STORAGE_ROOT_MARKER_FILE);
+  const marker = JSON.parse(await readFile(markerPath, 'utf8'));
+  await writeFile(markerPath, JSON.stringify({ ...marker, schemaVersion: 1 }));
+  const metadata = join(resolveRuntimeHostManagedDeploymentAuthorityRoot(), rootId);
+  await mkdir(metadata, { recursive: true });
+  await writeFile(join(metadata, 'runtime-host-deployment.json'), JSON.stringify({
+    schemaVersion: 1, state: 'active', deploymentId: RECOVERY_DEPLOYMENT_ID, configRevision: 1,
+    deploymentRoot: join(base, 'deployment'), root: { id: rootId, path: identity.canonicalPath },
+    projectDirectoryRoots: [],
+    launch: { kind: 'exact_package', nodePath: process.execPath,
+      package: { kind: 'npm_registry', version: '0.1.0', integrity: `sha512-${Buffer.alloc(64, 1).toString('base64')}` } },
+    listeners: { localIpc: true, websocket: { host: '127.0.0.1', port: 7400, path: '/runtime-host' } },
+    lifecycle: { mode: 'supervised', provider: 'systemd_user', availability: 'session' }, reconciliation: { trigger: 'manual' },
+  }));
   const setupPackage = { kind: 'npm' as const, specifier: 'maka-agent@0.2.0' };
   await mkdir(rootPath, { recursive: true });
   await writeManagedLifecycle(clientDataRoot, rootPath, rootId);
@@ -382,9 +408,20 @@ test('repairs an existing managed Host with the current setup package and restar
   });
   t.after(() => service.close());
 
-  assert.deepEqual(await service.repairManagedStartup({ allowManualUpdate: true }), {
-    kind: 'repaired',
+  assert.deepEqual(await resolveDesktopStorageRoot(rootPath, { confirmRepair: async () => false }), identity);
+  const connection = await connectOrSpawnRuntimeHost({
+    rootPath, protocol: { min: RUNTIME_HOST_PROTOCOL_VERSION, max: RUNTIME_HOST_PROTOCOL_VERSION },
+    compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, candidateEntrypoint: 'must-not-launch.js',
   });
+  assert.equal(connection.kind, 'failed');
+  if (connection.kind !== 'failed') assert.fail('expected management admission');
+  assert.equal(connection.reason, 'managed_root_requires_operator');
+  const error = runtimeHostStartupError(connection.reason);
+  assert.equal(canRepairManagedRuntimeHostStartup(error), true);
+  const blocker = await service.resolveStartupRepair(error, new AbortController().signal);
+  assert.ok(blocker?.replacement);
+  assert.equal(blocker.activity, undefined);
+  assert.deepEqual(await blocker.replacement.execute('refuse_active_work', () => {}, 'explicit'), { kind: 'completed' });
   assert.deepEqual(actions, ['update', 'restart']);
   assert.deepEqual(phases, ['checking', 'staging', 'restart']);
 });

apps/desktop/src/main/__tests__/runtime-host-management.test.ts

@@ -752,6 +752,7 @@ test('publishes update progress and waits for the managed profile to reconnect',
   assert.equal((response as { accessManagementAvailable: boolean }).accessManagementAvailable, true);
   assert.deepEqual(updates, [{
     destination: profile.transport.destination,
+    allowManualUpdate: true,
     setupPackage: { kind: 'npm', specifier: 'maka-agent@1.3.0' },
     operator: service.operator,
     expectedTarget: {

apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts

@@ -544,6 +544,7 @@ test('runs an exact update package and reports progress before an active-work re
       destination: 'operator@example.com',
       setupPackage: { kind: 'npm', specifier: 'maka-agent@1.3.0' },
       operator: OPERATOR,
+      allowManualUpdate: true,
       expectedTarget: {
         serviceId: 'b'.repeat(64),
         rootPath: '/srv/maka',
@@ -558,6 +559,7 @@ test('runs an exact update package and reports progress before an active-work re
   assert.match(remoteCommand, /--package.*maka-agent@1\.3\.0/u);
   assert.match(remoteCommand, /runtime-host.*service.*update/u);
   assert.match(remoteCommand, /--target.*1\.3\.0/u);
+  assert.match(remoteCommand, /--allow-manual-update/u);
   assert.match(remoteCommand, /--managed-root-id.*a{64}/u);
   assert.doesNotMatch(remoteCommand, /--operator-deployment-id/u);
   assert.match(remoteCommand, /MAKA_RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST/u);

apps/desktop/src/main/__tests__/storage-root-startup.test.ts

@@ -18,6 +18,7 @@
  */
 
 import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
 import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -29,6 +30,31 @@ import {
 } from '@maka/storage/root-authority';
 import { resolveDesktopStorageRoot } from '../storage-root-startup.js';
 
+test('Desktop startup reads identity without upgrading or granting business access', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'maka-desktop-identity-'));
+  try {
+    const initialized = await resolveDesktopStorageRoot(root, { confirmRepair: async () => false });
+    assert.ok(initialized);
+    const path = join(root, STORAGE_ROOT_MARKER_FILE);
+    const marker = JSON.parse(await readFile(path, 'utf8'));
+    for (const format of [
+      { schemaVersion: 1 },
+      { schemaVersion: 2, upgrade: { id: randomUUID() } },
+    ]) {
+      const persisted = JSON.stringify({ ...marker, ...format });
+      await writeFile(path, persisted);
+      const identity = await resolveDesktopStorageRoot(root, {
+        confirmRepair: async () => assert.fail('valid identity needs no repair'),
+      });
+      assert.deepEqual(identity, initialized);
+      assert.equal(await readFile(path, 'utf8'), persisted);
+      await assert.rejects(resolveStorageRoot({ path: root, kind: 'interactive' }), {
+        code: 'legacy_root_requires_migration',
+      });
+    }
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
 test('asks before adopting a root whose device number moved on its own', async () => {
   // A device number changes on its own whenever a volume is mounted again, so
   // repairing that case without asking is tempting: the person is being shown

apps/desktop/src/main/runtime-host-desktop-manager.ts

@@ -1285,7 +1285,11 @@ class RuntimeHostDesktopManagerImpl implements RuntimeHostDesktopManager {
         } };
       }
       if (await tryRecoverLocalHost()) continue;
-      const failure = runtimeHostStartupError(result.reason, result.diagnostic);
+      const failure = runtimeHostStartupError(
+        result.reason,
+        result.diagnostic,
+        'detail' in result ? result.detail : undefined,
+      );
       const repair = await resolveRepair(failure);
       if (repair) return repair;
       throw failure;

apps/desktop/src/main/runtime-host-local-management.ts

@@ -69,6 +69,8 @@ export function createDesktopRuntimeHostLocalManagement(input: {
             {
               setupPackage,
               target,
+              // This provider method is the user's explicit Settings update.
+              allowManualUpdate: true,
               ...(allowInterruptActiveTasks ? { allowInterruptActiveTasks: true } : {}),
             },
             onProgress,

apps/desktop/src/main/runtime-host-local-remote-access.ts

@@ -32,7 +32,7 @@ import {
   createRuntimeHostLegacyPosixOperatorCommand,
   runtimeHostManagedOperatorCommand,
   decodeRuntimeHostOperatorCommand,
-  resolveRuntimeHostManagedDeploymentAuthority,
+  inspectRuntimeHostManagedDeployment,
   type RuntimeHostOperatorCommand,
   type RuntimeHostServiceUpdatePhase,
 } from '@maka/runtime-host/operator';
@@ -212,8 +212,10 @@ export function createDesktopLocalRuntimeHostRemoteAccess(input: {
   const resolveManagedDeploymentAuthority =
     input.resolveManagedDeploymentAuthority ??
     (async (rootId: string): Promise<LocalManagedDeploymentAuthority | undefined> => {
-      const authority = await resolveRuntimeHostManagedDeploymentAuthority(rootId);
+      const authority = await inspectRuntimeHostManagedDeployment(rootId);
       if (!authority) return undefined;
+      if (authority.format === 'upgrading') return { kind: 'transition' };
+      if (!authority.record) return undefined;
       if (authority.record.state !== 'active') return { kind: 'transition' };
       return {
         kind: 'active',
@@ -814,10 +816,12 @@ export function createDesktopLocalRuntimeHostRemoteAccess(input: {
       const observed = await (input.inspectHost ?? connectExistingRuntimeHost)({
         rootPath: input.rootPath,
         protocol: { min: RUNTIME_HOST_PROTOCOL_VERSION, max: RUNTIME_HOST_PROTOCOL_VERSION },
-      });
-      const registration = 'registration' in observed ? observed.registration : undefined;
+      }).catch(() => undefined);
+      // Persisted deployment identity admits repair; unavailable live activity
+      // stays unknown and never authorizes automatic interruption.
+      const registration = observed && 'registration' in observed ? observed.registration : undefined;
       let activity: HostActivitySnapshot | undefined;
-      if (observed.kind === 'connected') {
+      if (observed?.kind === 'connected') {
         try {
           const facts = await observed.connection.request('host.diagnostics.query', {});
           if (facts.hostEpoch === observed.connection.hostEpoch && facts.pid === observed.registration.pid &&
@@ -830,7 +834,7 @@ export function createDesktopLocalRuntimeHostRemoteAccess(input: {
           }
         } catch { /* Missing activity evidence never authorizes automatic interruption. */ }
         finally { await observed.connection.close(); }
-      } else if (observed.kind === 'incompatible' || observed.kind === 'upgrade_required') {
+      } else if (observed?.kind === 'incompatible' || observed?.kind === 'upgrade_required') {
         if (observed.handshake?.state === 'ready') activity = observed.handshake.activity;
       }
       signal.throwIfAborted();

apps/desktop/src/main/runtime-host-management.ts

@@ -671,6 +671,7 @@ export function createDesktopRuntimeHostManagement(input: {
           setupPackage,
           operator: managed.control.operator,
           expectedTarget,
+          allowManualUpdate: true,
           ...(allowInterruptActiveTasksValue ? { allowInterruptActiveTasks: true } : {}),
         },
         (phase) => input.sendProgress({ profileId, phase }),

apps/desktop/src/main/runtime-host-ssh-terminal.ts

@@ -161,6 +161,7 @@ export interface DesktopRuntimeHostSshUpdateInput {
   readonly setupPackage: DesktopRuntimeHostSetupPackage;
   readonly operator: RuntimeHostOperatorCommand;
   readonly expectedTarget: DesktopRuntimeHostSshManagementInput['expectedTarget'];
+  readonly allowManualUpdate?: boolean;
   readonly allowInterruptActiveTasks?: boolean;
   readonly signal?: AbortSignal;
 }
@@ -1285,6 +1286,7 @@ function runtimeHostUpdateRemoteCommand(
       '--managed-root-id',
       input.expectedTarget.rootId,
       ...managedServiceTargetArgs(input.expectedTarget),
+      ...(input.allowManualUpdate && targetVersion ? ['--allow-manual-update'] : []),
       ...(input.allowInterruptActiveTasks ? ['--allow-interrupt-active-tasks'] : []),
     ],
     {