dsh-apk-vm 0.12.5 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/client.js CHANGED
@@ -30,7 +30,7 @@ window.__ModuleLoader__.load({
30
30
  var SWIPE_THRESHOLD_PX = 24;
31
31
  var FRAME_INTERVAL_MS = 500;
32
32
  var STATE_INTERVAL_MS = 2000;
33
- var CLIENT_VERSION = '0.12.5';
33
+ var CLIENT_VERSION = '0.13.0';
34
34
 
35
35
  /* ------------------------------------------------------------------ *
36
36
  * Optional dsh-better-sidebar integration.
@@ -110,6 +110,7 @@ window.__ModuleLoader__.load({
110
110
  'state.booting': 'Booting',
111
111
  'state.ready': 'Ready',
112
112
  'state.error': 'Error',
113
+ 'state.suspended': 'Suspended',
113
114
  'pill.boot': 'boot {s}s',
114
115
  'pill.snapshot': 'quick {s}s',
115
116
  'pill.cold': 'cold {s}s',
@@ -126,6 +127,20 @@ window.__ModuleLoader__.load({
126
127
  'owner.busy': 'in use by {label}',
127
128
  'owner.scope': 'Scope',
128
129
  'owner.forceHint': 'Another owner holds this VM; release it first.',
130
+ 'owner.reserved': 'Reserved by {label} until {time}',
131
+ 'owner.takeover': 'Take over',
132
+ 'owner.takeoverOk': 'Took over the VM',
133
+ 'owner.takeoverHint': 'Another owner holds this VM. Take it over to control it; the change is recorded in the activity log.',
134
+ 'owner.locked': 'Locked by {label} since {time}',
135
+ 'owner.lock': 'Lock',
136
+ 'owner.unlock': 'Unlock',
137
+ 'owner.lockOk': 'VM locked for {label}',
138
+ 'owner.unlockOk': 'VM unlocked',
139
+ 'owner.lockHint': 'Locked: other agents and panel input are blocked until the lock owner (or a local admin) unlocks it.',
140
+ 'owner.lockPanelHint': 'Locking blocks other agents and panel input until you unlock it.',
141
+ 'owner.lockOff': 'Locks are disabled by configuration (lockEnforcement: off).',
142
+ 'owner.lockAgentsOnly': 'Locks only block other agents; this panel can still operate (lockEnforcement: agents).',
143
+ 'owner.lockUserOnly': 'Only the user can lock or unlock a VM (lockControl: user).',
129
144
  'owner.admin': 'Administrator — can operate every VM',
130
145
  'action.start': 'Start VM',
131
146
  'action.starting': 'Starting…',
@@ -306,6 +321,9 @@ window.__ModuleLoader__.load({
306
321
  'storage.cleanTemp': 'Clean temp',
307
322
  'storage.cleanSnapshots': 'Clean snapshots',
308
323
  'storage.cleanOrphans': 'Clean orphan AVDs',
324
+ 'storage.cleanCorrupt': 'Clean corrupt snapshots',
325
+ 'storage.cleanCrash': 'Clean crash dumps',
326
+ 'storage.reclaimable': 'Reclaimable',
309
327
  'storage.confirm': 'Click again to confirm',
310
328
  'storage.freed': 'Freed {size}',
311
329
  'storage.avds': '{size} AVDs',
@@ -391,6 +409,7 @@ window.__ModuleLoader__.load({
391
409
  'instances.delete': 'Destroy VM',
392
410
  'instances.created': 'Created instance {id}',
393
411
  'instances.destroyed': 'Destroyed instance {id}',
412
+ 'instances.confirmDestroy': 'Click Delete again to confirm destroying {id} (its AVD and data are deleted)',
394
413
  'instances.manage': 'VM instances',
395
414
  'instances.rename': 'Rename',
396
415
  'instances.renamePrompt': 'Display name for this VM',
@@ -523,6 +542,7 @@ window.__ModuleLoader__.load({
523
542
  'state.booting': '开机中',
524
543
  'state.ready': '已就绪',
525
544
  'state.error': '出错',
545
+ 'state.suspended': '已挂起',
526
546
  'pill.boot': '启动用时 {s} 秒',
527
547
  'pill.snapshot': '快照启动 {s} 秒',
528
548
  'pill.cold': '冷启动 {s} 秒',
@@ -539,6 +559,20 @@ window.__ModuleLoader__.load({
539
559
  'owner.busy': '被 {label} 占用',
540
560
  'owner.scope': '范围',
541
561
  'owner.forceHint': '其他使用者正在占用,请先释放。',
562
+ 'owner.reserved': '{label} 保留至 {time}',
563
+ 'owner.takeover': '接管',
564
+ 'owner.takeoverOk': '已接管虚拟机',
565
+ 'owner.takeoverHint': '其他使用者正在占用此虚拟机;点击「接管」即可操作,变更会记录到活动日志。',
566
+ 'owner.locked': '由 {label} 锁定({time} 起)',
567
+ 'owner.lock': '锁定',
568
+ 'owner.unlock': '解锁',
569
+ 'owner.lockOk': '已锁定虚拟机({label})',
570
+ 'owner.unlockOk': '已解锁虚拟机',
571
+ 'owner.lockHint': '已锁定:其他 Agent 与面板操作会被拒绝,直到锁所有者(或本地管理员)解锁。',
572
+ 'owner.lockPanelHint': '锁定后其他 Agent 与面板操作都会被拒绝,直到解锁。',
573
+ 'owner.lockOff': '配置已关闭操作锁(lockEnforcement: off)。',
574
+ 'owner.lockAgentsOnly': '操作锁只阻止其他 Agent,本面板仍可操作(lockEnforcement: agents)。',
575
+ 'owner.lockUserOnly': '只有用户可以加锁/解锁虚拟机(lockControl: user)。',
542
576
  'owner.admin': '管理员 · 可操作所有虚拟机',
543
577
  'action.start': '启动虚拟机',
544
578
  'action.starting': '正在启动…',
@@ -719,6 +753,9 @@ window.__ModuleLoader__.load({
719
753
  'storage.cleanTemp': '清理临时文件',
720
754
  'storage.cleanSnapshots': '清理快照',
721
755
  'storage.cleanOrphans': '清理孤立 AVD',
756
+ 'storage.cleanCorrupt': '清理损坏快照',
757
+ 'storage.cleanCrash': '清理崩溃转储',
758
+ 'storage.reclaimable': '可回收',
722
759
  'storage.confirm': '再点一次确认',
723
760
  'storage.freed': '已释放 {size}',
724
761
  'storage.avds': '{size} 个 AVD',
@@ -804,6 +841,7 @@ window.__ModuleLoader__.load({
804
841
  'instances.delete': '销毁虚拟机',
805
842
  'instances.created': '已创建实例 {id}',
806
843
  'instances.destroyed': '已销毁实例 {id}',
844
+ 'instances.confirmDestroy': '再次点击删除以确认销毁 {id}(该实例的 AVD 与数据会被删除)',
807
845
  'instances.manage': '虚拟机实例',
808
846
  'instances.rename': '重命名',
809
847
  'instances.renamePrompt': '为这台虚拟机设置显示名称',
@@ -1191,6 +1229,13 @@ window.__ModuleLoader__.load({
1191
1229
  }
1192
1230
 
1193
1231
  var bootMs = Number(vmRaw.bootMs);
1232
+ var lockPolicy = { enforcement: 'all', control: 'all' };
1233
+ if (isObject(data.lockPolicy)) {
1234
+ var lockEnforcement = String(data.lockPolicy.enforcement || '');
1235
+ var lockControl = String(data.lockPolicy.control || '');
1236
+ if (lockEnforcement === 'agents' || lockEnforcement === 'off') lockPolicy.enforcement = lockEnforcement;
1237
+ if (lockControl === 'user') lockPolicy.control = lockControl;
1238
+ }
1194
1239
  return {
1195
1240
  vm: {
1196
1241
  state: state,
@@ -1209,6 +1254,7 @@ window.__ModuleLoader__.load({
1209
1254
  origin: typeof data.origin === 'string' && data.origin ? data.origin : '',
1210
1255
  memory: isObject(data.memory) ? data.memory : null,
1211
1256
  multiInstance: data.multiInstance === true,
1257
+ lockPolicy: lockPolicy,
1212
1258
  };
1213
1259
  }
1214
1260
 
@@ -2586,6 +2632,9 @@ window.__ModuleLoader__.load({
2586
2632
  var instanceBusyState = React.useState(false);
2587
2633
  var instanceBusy = instanceBusyState[0];
2588
2634
  var setInstanceBusy = instanceBusyState[1];
2635
+ var instanceConfirmState = React.useState('');
2636
+ var instanceConfirm = instanceConfirmState[0];
2637
+ var setInstanceConfirm = instanceConfirmState[1];
2589
2638
 
2590
2639
  var textInputState = React.useState('');
2591
2640
  var textInput = textInputState[0];
@@ -3439,6 +3488,16 @@ window.__ModuleLoader__.load({
3439
3488
  return Boolean(ownership && isObject(ownership.owner) && ownership.owner.key === panelOwnerKey());
3440
3489
  }
3441
3490
 
3491
+ function formatOwnerTime(value) {
3492
+ var stamp = Number(value);
3493
+ if (!isFinite(stamp) || stamp <= 0) return '';
3494
+ try {
3495
+ return new Date(stamp).toLocaleString();
3496
+ } catch (error) {
3497
+ return '';
3498
+ }
3499
+ }
3500
+
3442
3501
  function claimPanelOwner(force) {
3443
3502
  if (ownerBusy) return;
3444
3503
  var id = activeInstanceRef.current || 'default';
@@ -3461,8 +3520,66 @@ window.__ModuleLoader__.load({
3461
3520
  loadOwnership();
3462
3521
  return;
3463
3522
  }
3464
- pushToast('success', T('owner.claimOk'));
3523
+ pushToast('success', force === true ? T('owner.takeoverOk') : T('owner.claimOk'));
3524
+ loadOwnership();
3525
+ loadInstances();
3526
+ loadState();
3527
+ });
3528
+ }
3529
+
3530
+ function lockPanelOwner() {
3531
+ if (ownerBusy) return;
3532
+ var id = activeInstanceRef.current || 'default';
3533
+ setOwnerBusy(true);
3534
+ requestJson('/apk-vm/ownership', {
3535
+ method: 'POST',
3536
+ body: JSON.stringify({
3537
+ action: 'lock',
3538
+ instanceId: id,
3539
+ ownerKey: panelOwnerKey(),
3540
+ ownerScope: panelScope,
3541
+ ownerLabel: '桌面面板',
3542
+ }),
3543
+ }, T).then(function (result) {
3544
+ if (!mountedRef.current) return;
3545
+ setOwnerBusy(false);
3546
+ if (!result.ok) {
3547
+ pushToast('error', (result.error || T('err.action')).slice(0, 400));
3548
+ loadOwnership();
3549
+ return;
3550
+ }
3551
+ pushToast('success', T('owner.lockOk', { label: (result.owner && result.owner.label) || '桌面面板' }));
3552
+ loadOwnership();
3553
+ loadInstances();
3554
+ loadState();
3555
+ });
3556
+ }
3557
+
3558
+ function unlockPanelOwner() {
3559
+ if (ownerBusy) return;
3560
+ var id = activeInstanceRef.current || 'default';
3561
+ setOwnerBusy(true);
3562
+ requestJson('/apk-vm/ownership', {
3563
+ method: 'POST',
3564
+ body: JSON.stringify({
3565
+ action: 'unlock',
3566
+ instanceId: id,
3567
+ ownerKey: panelOwnerKey(),
3568
+ ownerScope: panelScope,
3569
+ ownerLabel: '桌面面板',
3570
+ force: true,
3571
+ }),
3572
+ }, T).then(function (result) {
3573
+ if (!mountedRef.current) return;
3574
+ setOwnerBusy(false);
3575
+ if (!result.ok) {
3576
+ pushToast('error', (result.error || T('err.action')).slice(0, 400));
3577
+ loadOwnership();
3578
+ return;
3579
+ }
3580
+ pushToast('success', T('owner.unlockOk'));
3465
3581
  loadOwnership();
3582
+ loadInstances();
3466
3583
  loadState();
3467
3584
  });
3468
3585
  }
@@ -3636,8 +3753,14 @@ window.__ModuleLoader__.load({
3636
3753
 
3637
3754
  function destroyInstanceById(id) {
3638
3755
  if (!id || id === 'default' || instanceBusy) return;
3756
+ if (instanceConfirm !== id) {
3757
+ setInstanceConfirm(id);
3758
+ pushToast('success', T('instances.confirmDestroy', { id: id }));
3759
+ return;
3760
+ }
3761
+ setInstanceConfirm('');
3639
3762
  setInstanceBusy(true);
3640
- requestJson('/apk-vm/instances/' + encodeURIComponent(id), { method: 'DELETE' }, T).then(function (result) {
3763
+ requestJson('/apk-vm/instances/' + encodeURIComponent(id) + '?confirm=1', { method: 'DELETE' }, T).then(function (result) {
3641
3764
  if (!mountedRef.current) return;
3642
3765
  setInstanceBusy(false);
3643
3766
  if (!result.ok) {
@@ -4265,7 +4388,11 @@ window.__ModuleLoader__.load({
4265
4388
 
4266
4389
  function cleanStorage(action) {
4267
4390
  if (storageBusy) return;
4268
- var destructive = action === 'snapshots' || action === 'orphan-avds';
4391
+ var destructive =
4392
+ action === 'snapshots' ||
4393
+ action === 'orphan-avds' ||
4394
+ action === 'corrupt-snapshots' ||
4395
+ action === 'crash-dumps';
4269
4396
  if (destructive && storageConfirm !== action) {
4270
4397
  setStorageConfirm(action);
4271
4398
  pushToast('success', T('storage.confirm'));
@@ -4278,7 +4405,13 @@ window.__ModuleLoader__.load({
4278
4405
  payload.avdName = storageSnapshotAvd();
4279
4406
  payload.confirm = true;
4280
4407
  }
4281
- if (action === 'orphan-avds') payload.confirm = true;
4408
+ if (
4409
+ action === 'orphan-avds' ||
4410
+ action === 'corrupt-snapshots' ||
4411
+ action === 'crash-dumps'
4412
+ ) {
4413
+ payload.confirm = true;
4414
+ }
4282
4415
  requestJson('/apk-vm/storage', { method: 'POST', body: JSON.stringify(payload) }, T).then(function (result) {
4283
4416
  if (!mountedRef.current) return;
4284
4417
  setStorageBusy('');
@@ -6124,6 +6257,14 @@ window.__ModuleLoader__.load({
6124
6257
  var currentOwner = ownership && isObject(ownership.owner) ? ownership.owner : null;
6125
6258
  var panelOwns = Boolean(currentOwner && currentOwner.key === panelOwnerKey());
6126
6259
  var ownerLabel = currentOwner ? String(currentOwner.label || currentOwner.key) : T('owner.none');
6260
+ var ownerReservedUntil = currentOwner && Number(currentOwner.reservedUntil) > 0 ? Number(currentOwner.reservedUntil) : 0;
6261
+ var ownerReservedText = ownerReservedUntil ? formatOwnerTime(ownerReservedUntil) : '';
6262
+ var ownerLocked = Boolean(currentOwner && currentOwner.locked === true);
6263
+ var ownerLockedAt = ownerLocked && Number(currentOwner.lockedAt) > 0 ? formatOwnerTime(Number(currentOwner.lockedAt)) : '';
6264
+ var lockPolicy = snapshot && isObject(snapshot.lockPolicy) ? snapshot.lockPolicy : { enforcement: 'all', control: 'all' };
6265
+ var lockDisabled = lockPolicy.enforcement === 'off';
6266
+ var lockAgentsOnly = lockPolicy.enforcement === 'agents';
6267
+ var lockUserOnly = lockPolicy.control === 'user';
6127
6268
  var ownerCard = h(
6128
6269
  'details',
6129
6270
  { className: 'apkvm-card apkvm-owner', open: true },
@@ -6146,6 +6287,19 @@ window.__ModuleLoader__.load({
6146
6287
  ? h('span', { className: 'apkvm-dim' }, ' · ' + T('owner.busy', { label: ownerLabel }))
6147
6288
  : null
6148
6289
  ),
6290
+ ownerReservedText
6291
+ ? h('div', { className: 'apkvm-dim' }, T('owner.reserved', { label: ownerLabel, time: ownerReservedText }))
6292
+ : null,
6293
+ ownerLocked
6294
+ ? h('div', { className: 'apkvm-dim' }, T('owner.locked', { label: ownerLabel, time: ownerLockedAt || '' }))
6295
+ : null,
6296
+ lockDisabled
6297
+ ? h('div', { className: 'apkvm-dim' }, T('owner.lockOff'))
6298
+ : lockAgentsOnly
6299
+ ? h('div', { className: 'apkvm-dim' }, T('owner.lockAgentsOnly'))
6300
+ : lockUserOnly
6301
+ ? h('div', { className: 'apkvm-dim' }, T('owner.lockUserOnly'))
6302
+ : null,
6149
6303
  h(
6150
6304
  'div',
6151
6305
  { className: 'apkvm-ownercontrols' },
@@ -6166,12 +6320,62 @@ window.__ModuleLoader__.load({
6166
6320
  T('owner.' + scope)
6167
6321
  );
6168
6322
  }),
6323
+ currentOwner && !panelOwns
6324
+ ? h(
6325
+ 'button',
6326
+ {
6327
+ key: 'takeover',
6328
+ type: 'button',
6329
+ className: 'apkvm-mini',
6330
+ disabled: ownerBusy,
6331
+ title: T('owner.takeoverHint'),
6332
+ onClick: function (event) {
6333
+ event.preventDefault();
6334
+ claimPanelOwner(true);
6335
+ },
6336
+ },
6337
+ T('owner.takeover')
6338
+ )
6339
+ : null,
6340
+ panelOwns && !ownerLocked && !lockDisabled
6341
+ ? h(
6342
+ 'button',
6343
+ {
6344
+ key: 'lock',
6345
+ type: 'button',
6346
+ className: 'apkvm-mini',
6347
+ disabled: ownerBusy,
6348
+ title: T('owner.lockPanelHint'),
6349
+ onClick: function (event) {
6350
+ event.preventDefault();
6351
+ lockPanelOwner();
6352
+ },
6353
+ },
6354
+ T('owner.lock')
6355
+ )
6356
+ : null,
6357
+ ownerLocked
6358
+ ? h(
6359
+ 'button',
6360
+ {
6361
+ key: 'unlock',
6362
+ type: 'button',
6363
+ className: 'apkvm-mini',
6364
+ disabled: ownerBusy,
6365
+ onClick: function (event) {
6366
+ event.preventDefault();
6367
+ unlockPanelOwner();
6368
+ },
6369
+ },
6370
+ T('owner.unlock')
6371
+ )
6372
+ : null,
6169
6373
  h(
6170
6374
  'button',
6171
6375
  {
6172
6376
  type: 'button',
6173
6377
  className: 'apkvm-mini',
6174
- disabled: ownerBusy || panelOwns,
6378
+ disabled: ownerBusy || panelOwns || Boolean(currentOwner),
6175
6379
  onClick: function (event) {
6176
6380
  event.preventDefault();
6177
6381
  claimPanelOwner(false);
@@ -6194,7 +6398,7 @@ window.__ModuleLoader__.load({
6194
6398
  )
6195
6399
  ),
6196
6400
  currentOwner && !panelOwns
6197
- ? h('div', { className: 'apkvm-dim' }, T('owner.forceHint'))
6401
+ ? h('div', { className: 'apkvm-dim' }, ownerLocked ? T('owner.lockHint') : T('owner.takeoverHint'))
6198
6402
  : null
6199
6403
  )
6200
6404
  );
@@ -7067,6 +7271,11 @@ window.__ModuleLoader__.load({
7067
7271
  h('span', null, T('storage.snapshots') + ': ' + formatBytes((storage.totals && storage.totals.snapshotBytes) || 0)),
7068
7272
  h('span', null, T('storage.sdk') + ': ' + formatBytes((storage.totals && storage.totals.sdkBytes) || 0)),
7069
7273
  h('span', null, T('storage.temp') + ': ' + formatBytes((storage.totals && storage.totals.tempBytes) || 0)),
7274
+ h(
7275
+ 'span',
7276
+ null,
7277
+ T('storage.reclaimable') + ': ' + formatBytes((storage.totals && storage.totals.reclaimableBytes) || 0)
7278
+ ),
7070
7279
  storage.disk
7071
7280
  ? h('span', null, T('storage.free') + ': ' + formatBytes(storage.disk.freeBytes))
7072
7281
  : null
@@ -7129,6 +7338,40 @@ window.__ModuleLoader__.load({
7129
7338
  },
7130
7339
  }
7131
7340
  ),
7341
+ storage.totals && storage.totals.corruptBytes
7342
+ ? actionBtn(
7343
+ storageConfirm === 'corrupt-snapshots'
7344
+ ? T('storage.confirm')
7345
+ : storageBusy === 'corrupt-snapshots'
7346
+ ? '…'
7347
+ : T('storage.cleanCorrupt'),
7348
+ {
7349
+ key: 'storage-corrupt',
7350
+ small: true,
7351
+ disabled: Boolean(storageBusy),
7352
+ onClick: function () {
7353
+ cleanStorage('corrupt-snapshots');
7354
+ },
7355
+ }
7356
+ )
7357
+ : null,
7358
+ storage.totals && storage.totals.crashBytes
7359
+ ? actionBtn(
7360
+ storageConfirm === 'crash-dumps'
7361
+ ? T('storage.confirm')
7362
+ : storageBusy === 'crash-dumps'
7363
+ ? '…'
7364
+ : T('storage.cleanCrash'),
7365
+ {
7366
+ key: 'storage-crash',
7367
+ small: true,
7368
+ disabled: Boolean(storageBusy),
7369
+ onClick: function () {
7370
+ cleanStorage('crash-dumps');
7371
+ },
7372
+ }
7373
+ )
7374
+ : null,
7132
7375
  (storage.recommendations || []).some(function (item) {
7133
7376
  return item.code === 'orphan-avds';
7134
7377
  }) || (storage.avds || []).some(function (item) {
package/cordis.patch.yml CHANGED
@@ -45,6 +45,24 @@
45
45
  # quick reuse. start()/the next Agent action boots it again.
46
46
  instanceIdleMs: 900000
47
47
  instanceReapIntervalMs: 60000
48
+ # Resident shared default VM: a lease can be released, but the VM and its
49
+ # AVD are never released or deleted. After sharedSuspendAfterMs idle the
50
+ # default VM suspends into its quick-boot snapshot (state "suspended",
51
+ # ~6 s to resume); after sharedStopAfterMs it is marked "stopped" (the
52
+ # snapshot and AVD are kept). Tool calls, panel actions and video clients
53
+ # reset the idle timer and a later start resumes it on demand.
54
+ sharedResident: true
55
+ sharedSuspendAfterMs: 300000
56
+ sharedStopAfterMs: 3600000
57
+ # Operation locks (lock_vm / panel Lock): a locked VM rejects other
58
+ # agents and users until the lock owner (or a local admin) unlocks it.
59
+ # lockEnforcement: all = hard lock for everyone; agents = only other
60
+ # agents are blocked, the local panel can still operate; off = locks are
61
+ # advisory markers only (never block).
62
+ lockEnforcement: all
63
+ # lockControl: all = agents or the panel may lock/unlock; user = only the
64
+ # panel/user can lock/unlock (tool lock_vm/unlock_vm return an error).
65
+ lockControl: all
48
66
  # Host memory guard: refuse to start another local VM when the machine is
49
67
  # low on memory, and cap the effective instance count from total RAM.
50
68
  # A local emulator costs ~2-3 GB (AVD 1.5 GB + qemu/GPU overhead), so
package/docs/AGENTS.md CHANGED
@@ -26,9 +26,11 @@ or `GET /apk-vm/guide`. The tool description also points here.
26
26
 
27
27
  ## Mental model
28
28
 
29
- - The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`).
30
- A VM owned by another conversation returns a `vm-busy` error; `ownerForce: true` is an
31
- explicit takeover and should only be used when the user asked for it.
29
+ - The VM is a **leased device**. Leases have a scope (`shared`, `conversation`, `project`) and are
30
+ persisted to `<profile>/.apk-vm/leases.json`. A VM owned by another conversation returns a
31
+ `vm-busy` error (or `vm-takeover-required` for an admin panel action); `ownerForce: true`
32
+ (alias `force: true`) is an explicit takeover and should only be used when the user asked for
33
+ it. Dedicated (`conversation`/`project`) leases stay reserved for 24 h by default.
32
34
  - **Only `ready` VMs accept input.** `info` returns `state`, `root`, `serial`, `size`,
33
35
  `density`, `dpr` and `coordinateMap`.
34
36
  - `instance` selects the VM: omit it to use the calling agent's assignment (the first
@@ -74,7 +76,7 @@ or `GET /apk-vm/guide`. The tool description also points here.
74
76
  (`overlay: true` draws UIAutomator boxes), `record`, `perf`, `rotate`
75
77
  - **Instances & leases:** `list_instances`, `create_instance`, `rename_instance`, `destroy_instance`,
76
78
  `owner_status`, `claim_vm`, `release_vm`, `ownerScope` (`shared|conversation|project`),
77
- `ownerForce`
79
+ `ownerForce` (alias `force`)
78
80
  - **Network / environment:** `network`, `proxy`, `env_snapshot`, `env_restore`, `install_ca`
79
81
  - **Flows and skills:** `flow_*` (record/replay a journey), `skill_*` (persisted app-operation
80
82
  skills with a Control Codebook), `control_*` (semantic-code tap/input, more layout-stable
@@ -116,10 +118,13 @@ call. `action=guide` is always available and never touches a VM.
116
118
 
117
119
  ## Shared vs dedicated VMs
118
120
 
119
- The default instance is a **shared** device: every conversation may use it, it is
120
- short-lived, and entering it from a different conversation resets the guest to the home
121
- screen (so you never inherit someone else's foreground app). Use it for one-off inspection
122
- and short automations.
121
+ The default instance is a **shared, resident** device: every conversation may use it, and it is
122
+ never released or deleted. When idle for `sharedSuspendAfterMs` (5 min) it suspends into its
123
+ quick-boot snapshot (state `suspended`; a start resumes it in ~6 s); after `sharedStopAfterMs`
124
+ (1 h) suspended it is marked `stopped`. The AVD and snapshot are kept. Any `apk_vm` call, panel
125
+ action or video client resets the idle timer, and a later start resumes it on demand.
126
+ Entering it from a different conversation resets the guest to the home screen (so you never
127
+ inherit someone else's foreground app). Use it for one-off inspection and short automations.
123
128
 
124
129
  If this conversation needs a long-lived debugging device — logins, installed apps, stable
125
130
  state — claim a dedicated VM instead of holding the shared one:
@@ -130,7 +135,22 @@ state — claim a dedicated VM instead of holding the shared one:
130
135
  - `owner_status` inspects leases; `release_vm` gives a VM back.
131
136
 
132
137
  Don't keep several agents on one shared VM. Leases are visible in the panel, and a VM owned
133
- by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true`).
138
+ by another conversation returns `vm-busy` unless you force a takeover (`ownerForce=true`, alias
139
+ `force=true`). Dedicated reservations survive plugin restarts; the panel needs an explicit takeover
140
+ (`x-apk-vm-takeover: 1`) for a VM held by another owner.
141
+
142
+ ## VM operation locks
143
+
144
+ `lock_vm` / `unlock_vm` (or `POST /apk-vm/ownership` actions `lock`/`unlock`) make the current
145
+ owner's lease a hard lock. While locked, every mutating request from another agent or the panel
146
+ is rejected with `409 vm-locked`; `ownerForce`/takeover cannot break it. The panel owner card
147
+ shows the lock and offers Lock/Unlock; a local admin can force-unlock. A lock does not block
148
+ read-only calls (`owner_status`, `list_instances`, `info`).
149
+
150
+ The plugin configuration can relax this: `lockEnforcement: agents` blocks only other agents
151
+ (the local panel can still operate a locked VM) and `off` makes locks advisory only;
152
+ `lockControl: user` limits lock/unlock to the panel/user (`lock_vm`/`unlock_vm` return a
153
+ `vm-lock-restricted` error).
134
154
 
135
155
  ## Instances and remote VMs
136
156
 
@@ -179,11 +199,21 @@ which can fit a third VM.
179
199
  readiness usually arrives within a couple of seconds.
180
200
  - Screenshot or device timeouts return structured error codes (for example
181
201
  `EDEVICE_UNRESPONSIVE`); if the guest is wedged, `stop` + `start` is the recovery.
182
- - `vm-busy`: inspect with `owner_status`; `release_vm` frees a lease, `claim_vm` with
183
- `ownerForce: true` is an explicit takeover.
202
+ - `vm-busy` / `vm-takeover-required`: inspect with `owner_status`; `release_vm` frees a lease,
203
+ `claim_vm` with `ownerForce: true` (alias `force: true`) is an explicit takeover. A reserved
204
+ lease stays reserved until `reservedUntil`, even across plugin restarts.
184
205
  - Failed calls are journaled too (`ok: false` with the error); read the activity log before
185
206
  retrying the same action.
186
-
207
+ - Destructive actions need explicit confirmation: `destroy_instance` requires `confirm: true`,
208
+ and `clean_storage` requires `confirm: true` for `snapshots`, `orphan-avds`,
209
+ `corrupt-snapshots` and `crash-dumps`. Never set `confirm` before checking the instance name
210
+ and the reported reclaimable bytes.
211
+ - An action that has to boot a VM now fails after about 120 s (explicit `start`: 180 s) with an
212
+ actionable error instead of blocking for the 20-minute boot timeout; inspect `state`/
213
+ `logTail`, stop a wedged VM, then retry.
214
+
215
+ - `vm-locked`: the VM is hard-locked by its owner; `ownerForce`/takeover does not override a
216
+ lock. The lock owner can `unlock_vm`; the local panel offers Unlock (admin can force-unlock).
187
217
  ## Suggested agent instructions
188
218
 
189
219
  ```text
package/docs/PRIVACY.md CHANGED
@@ -30,6 +30,12 @@ reporting, advertising or a remote backend.
30
30
  default) and can be cleared from the panel or with `POST /apk-vm/activity/clear`.
31
31
  Because entries can contain screen content and command arguments (typed text is recorded
32
32
  as a character count only), clear the journal before sharing the panel or its recordings.
33
+ - **Persisted VM leases.** `<profile>/.apk-vm/leases.json` stores the owner key, scope, session id,
34
+ workspace, display label and dedicated-reservation deadline for VM leases so that a
35
+ `conversation`/`project` VM stays reserved across DSH restarts. It is written only for VM
36
+ ownership bookkeeping, stays on this host and contains no screen content; delete the file
37
+ (or release the lease) to clear it. Leases record the DSH session id and workspace path, which
38
+ may be visible to other local conversations if the panel or activity log is shared.
33
39
  - **Remembered installed apps.** `<profile>/.apk-vm/installed-apps.json` stores the APK path,
34
40
  package name, label, launch activity and instance for APKs installed through the plugin, and
35
41
  archived copies live under `<profile>/.apk-vm/apks` (newest 10). Both stay on this host and are