agent-steward 0.0.4 → 0.0.5

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.
Files changed (190) hide show
  1. package/CHANGELOG.md +134 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +52 -7
  4. package/ROADMAP-STRATEGY.md +21 -18
  5. package/ROADMAP.md +140 -159
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +351 -0
  9. package/dist/core/execution.d.ts +203 -0
  10. package/dist/core/execution.d.ts.map +1 -0
  11. package/dist/core/execution.js +309 -0
  12. package/dist/core/gate-integrity.d.ts +35 -0
  13. package/dist/core/gate-integrity.d.ts.map +1 -0
  14. package/dist/core/gate-integrity.js +132 -0
  15. package/dist/core/git-trigger.d.ts.map +1 -1
  16. package/dist/core/git-trigger.js +14 -2
  17. package/dist/core/guard-run.d.ts +4 -0
  18. package/dist/core/guard-run.d.ts.map +1 -0
  19. package/dist/core/guard-run.js +101 -0
  20. package/dist/core/guard.d.ts +52 -0
  21. package/dist/core/guard.d.ts.map +1 -0
  22. package/dist/core/guard.js +362 -0
  23. package/dist/core/lock.d.ts +41 -0
  24. package/dist/core/lock.d.ts.map +1 -1
  25. package/dist/core/lock.js +141 -29
  26. package/dist/core/matrix.d.ts.map +1 -1
  27. package/dist/core/matrix.js +75 -15
  28. package/dist/core/mission.d.ts +83 -0
  29. package/dist/core/mission.d.ts.map +1 -0
  30. package/dist/core/mission.js +334 -0
  31. package/dist/core/pipeline-apply.d.ts +38 -0
  32. package/dist/core/pipeline-apply.d.ts.map +1 -0
  33. package/dist/core/pipeline-apply.js +117 -0
  34. package/dist/core/pipeline-io.d.ts +13 -0
  35. package/dist/core/pipeline-io.d.ts.map +1 -0
  36. package/dist/core/pipeline-io.js +64 -0
  37. package/dist/core/pipeline-map.d.ts +46 -0
  38. package/dist/core/pipeline-map.d.ts.map +1 -0
  39. package/dist/core/pipeline-map.js +196 -0
  40. package/dist/core/pipeline-spec.d.ts +109 -0
  41. package/dist/core/pipeline-spec.d.ts.map +1 -0
  42. package/dist/core/pipeline-spec.js +554 -0
  43. package/dist/core/ps-wrapper.d.ts +19 -2
  44. package/dist/core/ps-wrapper.d.ts.map +1 -1
  45. package/dist/core/ps-wrapper.js +250 -62
  46. package/dist/core/record-history.d.ts.map +1 -1
  47. package/dist/core/record-history.js +130 -29
  48. package/dist/core/router/rules.d.ts.map +1 -1
  49. package/dist/core/router/rules.js +6 -0
  50. package/dist/core/scheduler/linux.d.ts +8 -1
  51. package/dist/core/scheduler/linux.d.ts.map +1 -1
  52. package/dist/core/scheduler/linux.js +34 -9
  53. package/dist/core/scheduler/mac.d.ts +44 -2
  54. package/dist/core/scheduler/mac.d.ts.map +1 -1
  55. package/dist/core/scheduler/mac.js +126 -15
  56. package/dist/core/scheduler/windows.d.ts.map +1 -1
  57. package/dist/core/scheduler/windows.js +15 -12
  58. package/dist/core/structured-log.d.ts +7 -1
  59. package/dist/core/structured-log.d.ts.map +1 -1
  60. package/dist/core/worktree-run.d.ts +4 -0
  61. package/dist/core/worktree-run.d.ts.map +1 -0
  62. package/dist/core/worktree-run.js +164 -0
  63. package/dist/core/worktree.d.ts +115 -0
  64. package/dist/core/worktree.d.ts.map +1 -0
  65. package/dist/core/worktree.js +462 -0
  66. package/dist/core/wrappers/bash.d.ts +17 -0
  67. package/dist/core/wrappers/bash.d.ts.map +1 -1
  68. package/dist/core/wrappers/bash.js +175 -24
  69. package/dist/db/capability-repo.d.ts +43 -2
  70. package/dist/db/capability-repo.d.ts.map +1 -1
  71. package/dist/db/capability-repo.js +96 -11
  72. package/dist/db/history-repo.d.ts +38 -5
  73. package/dist/db/history-repo.d.ts.map +1 -1
  74. package/dist/db/history-repo.js +88 -25
  75. package/dist/db/metrics-repo.js +2 -2
  76. package/dist/db/recovery.d.ts.map +1 -1
  77. package/dist/db/recovery.js +5 -4
  78. package/dist/db/run-journal.d.ts +33 -5
  79. package/dist/db/run-journal.d.ts.map +1 -1
  80. package/dist/db/run-journal.js +78 -14
  81. package/dist/db/run-resume.d.ts +5 -0
  82. package/dist/db/run-resume.d.ts.map +1 -1
  83. package/dist/db/run-resume.js +9 -2
  84. package/dist/db/runs-repo.d.ts +19 -2
  85. package/dist/db/runs-repo.d.ts.map +1 -1
  86. package/dist/db/runs-repo.js +22 -6
  87. package/dist/db/schema.d.ts +2 -2
  88. package/dist/db/schema.d.ts.map +1 -1
  89. package/dist/db/schema.js +63 -2
  90. package/dist/history.d.ts +1 -1
  91. package/dist/history.d.ts.map +1 -1
  92. package/dist/i18n.d.ts +5 -0
  93. package/dist/i18n.d.ts.map +1 -1
  94. package/dist/i18n.js +11 -4
  95. package/dist/index.d.ts +136 -2
  96. package/dist/index.d.ts.map +1 -1
  97. package/dist/index.js +378 -14
  98. package/dist/notifications.d.ts +22 -0
  99. package/dist/notifications.d.ts.map +1 -1
  100. package/dist/notifications.js +36 -8
  101. package/dist/profiles.d.ts.map +1 -1
  102. package/dist/profiles.js +25 -4
  103. package/dist/rpc.d.ts +246 -0
  104. package/dist/rpc.d.ts.map +1 -1
  105. package/dist/rpc.js +117 -0
  106. package/dist/server.d.ts +15 -0
  107. package/dist/server.d.ts.map +1 -1
  108. package/dist/server.js +77 -18
  109. package/dist/settings.d.ts +2 -2
  110. package/dist/settings.d.ts.map +1 -1
  111. package/dist/settings.js +3 -3
  112. package/dist/shared/jobs-view.d.ts +1 -1
  113. package/dist/shared/jobs-view.d.ts.map +1 -1
  114. package/dist/shared/jobs-view.js +2 -0
  115. package/dist/task-transfer.d.ts +16 -0
  116. package/dist/task-transfer.d.ts.map +1 -1
  117. package/dist/task-transfer.js +16 -0
  118. package/docs/ARCHITECTURE.md +281 -65
  119. package/docs/COMPATIBILITY.md +2 -2
  120. package/docs/CONCEPT.md +18 -4
  121. package/docs/CROSS_PLATFORM.ru.md +20 -0
  122. package/docs/CROSS_PLATFORM.zh.md +18 -0
  123. package/docs/EXECUTION-LOOP.md +22 -7
  124. package/docs/FEATURES.md +65 -4
  125. package/docs/FEATURES.zh.md +52 -4
  126. package/docs/MIGRATION.md +2 -2
  127. package/docs/PIPELINE.md +293 -0
  128. package/docs/README.ru.md +42 -3
  129. package/docs/README.zh.md +43 -3
  130. package/docs/SAFETY.md +23 -3
  131. package/gui-experimental.cjs +9 -8
  132. package/locales/en.json +17 -1
  133. package/locales/ru.json +17 -1
  134. package/locales/zh.json +17 -1
  135. package/opencode.pipeline.yaml +35 -0
  136. package/package.json +23 -4
  137. package/scripts/test-home.mjs +83 -0
  138. package/src/cli.ts +412 -0
  139. package/src/core/dry-run.ts +2 -2
  140. package/src/core/execution.ts +538 -0
  141. package/src/core/file-watcher.ts +2 -2
  142. package/src/core/gate-integrity.ts +160 -0
  143. package/src/core/git-trigger.ts +18 -5
  144. package/src/core/guard-run.ts +119 -0
  145. package/src/core/guard.ts +431 -0
  146. package/src/core/lock.ts +178 -37
  147. package/src/core/matrix.ts +95 -50
  148. package/src/core/mission.ts +485 -0
  149. package/src/core/native-notify.ts +1 -1
  150. package/src/core/pipeline-apply.ts +158 -0
  151. package/src/core/pipeline-io.ts +79 -0
  152. package/src/core/pipeline-map.ts +264 -0
  153. package/src/core/pipeline-spec.ts +775 -0
  154. package/src/core/ps-wrapper.ts +263 -63
  155. package/src/core/record-history.ts +164 -77
  156. package/src/core/router/rules.ts +6 -0
  157. package/src/core/schedule-gate.ts +1 -1
  158. package/src/core/scheduler/at-fallback.ts +1 -1
  159. package/src/core/scheduler/linux.ts +40 -11
  160. package/src/core/scheduler/logs.ts +2 -2
  161. package/src/core/scheduler/mac.ts +174 -14
  162. package/src/core/scheduler/registry.ts +2 -2
  163. package/src/core/scheduler/windows.ts +19 -15
  164. package/src/core/secrets.ts +8 -8
  165. package/src/core/structured-log.ts +22 -5
  166. package/src/core/telegram.ts +2 -2
  167. package/src/core/triage-worker.ts +7 -7
  168. package/src/core/triage.ts +2 -2
  169. package/src/core/worktree-run.ts +199 -0
  170. package/src/core/worktree.ts +600 -0
  171. package/src/core/wrappers/bash.ts +190 -23
  172. package/src/db/capability-repo.ts +127 -10
  173. package/src/db/history-repo.ts +129 -22
  174. package/src/db/metrics-repo.ts +2 -2
  175. package/src/db/recovery.ts +5 -4
  176. package/src/db/run-journal.ts +100 -13
  177. package/src/db/run-resume.ts +17 -1
  178. package/src/db/runs-repo.ts +36 -6
  179. package/src/db/schema.ts +65 -2
  180. package/src/gui.tsx +177 -13
  181. package/src/history.ts +1 -1
  182. package/src/i18n.ts +12 -4
  183. package/src/index.ts +524 -4
  184. package/src/notifications.ts +38 -8
  185. package/src/profiles.ts +26 -4
  186. package/src/rpc.ts +128 -0
  187. package/src/server.ts +94 -18
  188. package/src/settings.ts +5 -5
  189. package/src/shared/jobs-view.ts +3 -1
  190. package/src/task-transfer.ts +31 -0
@@ -1,6 +1,7 @@
1
1
  import { getDb, withTransaction } from "./index.js";
2
2
  import { incrementMetricsUnsafe } from "./metrics-repo.js";
3
3
  import { appendStructuredLog } from "../core/structured-log.js";
4
+ import os from "node:os";
4
5
  import type { TaskStatus } from "../history.js";
5
6
 
6
7
  /**
@@ -30,6 +31,10 @@ export interface StoredHistoryRecord {
30
31
  workspaceId?: string | null;
31
32
  allowedTools?: string[] | null;
32
33
  deniedTools?: string[] | null;
34
+ /** Владелец незавершённого запуска (схема v8). */
35
+ ownerPid?: number | null;
36
+ ownerHost?: string | null;
37
+ ownerStartedAt?: string | null;
33
38
  }
34
39
 
35
40
  /** Поля, которые пишутся в history при завершении запуска. */
@@ -73,14 +78,17 @@ function rowToRecord(row: any): StoredHistoryRecord {
73
78
  workspaceId: row.workspace_id == null ? null : String(row.workspace_id),
74
79
  allowedTools: row.allowed_tools == null ? null : JSON.parse(String(row.allowed_tools)),
75
80
  deniedTools: row.denied_tools == null ? null : JSON.parse(String(row.denied_tools)),
81
+ ownerPid: row.owner_pid == null ? null : Number(row.owner_pid),
82
+ ownerHost: row.owner_host == null ? null : String(row.owner_host),
83
+ ownerStartedAt: row.owner_started_at == null ? null : String(row.owner_started_at),
76
84
  };
77
85
  }
78
86
 
79
87
  const INSERT_SQL = `INSERT INTO history (
80
88
  task_name, status, started_at, finished_at, duration_ms, error,
81
89
  tokens, cost_usd, model, pre_flight_status, post_flight_status, next_task,
82
- workspace_id, allowed_tools, denied_tools
83
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
90
+ workspace_id, allowed_tools, denied_tools, owner_pid, owner_host, owner_started_at
91
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
84
92
 
85
93
  function lastId(result: { lastInsertRowid: number | bigint }): number {
86
94
  return Number(result.lastInsertRowid) || 0;
@@ -106,6 +114,9 @@ export function insertHistory(record: StoredHistoryRecord): number {
106
114
  record.workspaceId ?? null,
107
115
  record.allowedTools == null ? null : JSON.stringify(record.allowedTools),
108
116
  record.deniedTools == null ? null : JSON.stringify(record.deniedTools),
117
+ record.ownerPid ?? null,
118
+ record.ownerHost ?? null,
119
+ record.ownerStartedAt ?? null,
109
120
  );
110
121
  return lastId(result);
111
122
  }
@@ -117,6 +128,7 @@ export function startRun(
117
128
  workspaceId?: string | null,
118
129
  allowedTools?: string[] | null,
119
130
  deniedTools?: string[] | null,
131
+ owner?: { pid?: number | null; host?: string | null; startedAt?: string | null },
120
132
  ): number {
121
133
  const id = insertHistory({
122
134
  taskName,
@@ -126,6 +138,9 @@ export function startRun(
126
138
  workspaceId,
127
139
  allowedTools,
128
140
  deniedTools,
141
+ ownerPid: owner?.pid ?? null,
142
+ ownerHost: owner?.host ?? null,
143
+ ownerStartedAt: owner?.startedAt ?? null,
129
144
  });
130
145
  appendStructuredLog({
131
146
  event: "run.started",
@@ -262,6 +277,10 @@ export function recordRun(
262
277
  workspaceId ?? null,
263
278
  allowedTools == null ? null : JSON.stringify(allowedTools),
264
279
  deniedTools == null ? null : JSON.stringify(deniedTools),
280
+ // owner-колонки относятся только к незавершённым запускам (startRun).
281
+ null,
282
+ null,
283
+ null,
265
284
  );
266
285
  incrementMetricsUnsafe(taskName, status, tokens, costUsd);
267
286
  return lastId(result);
@@ -366,29 +385,117 @@ export function getHistorySince(
366
385
  }
367
386
 
368
387
  /**
369
- * Crash recovery: все незавершённые записи (finished_at IS NULL) помечаются
370
- * как error. Длительность считается от started_at до текущего момента.
371
- * Возвращает количество восстановленных записей.
388
+ * Crash recovery для истории.
389
+ *
390
+ * Незавершённая запись (finished_at IS NULL) финализируется как error, только
391
+ * если её владелец больше не может её завершить:
392
+ * - владелец известен, жив и на этом же хосте → запись оставляем (B1);
393
+ * - владелец известен и мёртв → финализируем сразу;
394
+ * - владелец неизвестен (legacy-строка или другой хост) → финализируем,
395
+ * только когда запись старше `maxUnverifiableAgeMs`.
372
396
  */
373
- export function recoverInterrupted(): number {
374
- const now = new Date().toISOString();
375
- const result = getDb()
397
+
398
+ /** Возраст, после которого запись с непроверяемым владельцем считается осиротевшей. */
399
+ export const UNVERIFIABLE_OWNER_MAX_AGE_MS = 24 * 60 * 60 * 1000;
400
+
401
+ export interface RecoverInterruptedResult {
402
+ /** Сколько записей финализировано как error. */
403
+ recovered: number;
404
+ /** Сколько записей оставлено живым владельцам. */
405
+ keptAlive: number;
406
+ }
407
+
408
+ export interface RecoverInterruptedOptions {
409
+ /** Текущий момент (для тестов). */
410
+ now?: Date;
411
+ /** Порог возраста для записей с непроверяемым владельцем. */
412
+ maxUnverifiableAgeMs?: number;
413
+ /** Имя текущего хоста (для тестов). */
414
+ hostname?: string;
415
+ /** Проверка живости PID (для тестов). */
416
+ isAlive?: (pid: number) => boolean;
417
+ }
418
+
419
+ /** Проверяет существование процесса: signal 0 не убивает, только пробует. */
420
+ export function isProcessAlive(pid: number): boolean {
421
+ if (!Number.isInteger(pid) || pid <= 0) return false;
422
+ try {
423
+ process.kill(pid, 0);
424
+ return true;
425
+ } catch (error) {
426
+ // EPERM — процесс существует, но сигнал запрещён; ESRCH — процесса нет.
427
+ return (error as NodeJS.ErrnoException)?.code === "EPERM";
428
+ }
429
+ }
430
+
431
+ export function recoverInterrupted(
432
+ options: RecoverInterruptedOptions = {},
433
+ ): RecoverInterruptedResult {
434
+ const now = options.now ?? new Date();
435
+ const nowIso = now.toISOString();
436
+ const maxAge =
437
+ typeof options.maxUnverifiableAgeMs === "number" &&
438
+ Number.isFinite(options.maxUnverifiableAgeMs)
439
+ ? Math.max(0, options.maxUnverifiableAgeMs)
440
+ : UNVERIFIABLE_OWNER_MAX_AGE_MS;
441
+ const hostname = options.hostname ?? os.hostname();
442
+ const isAlive = options.isAlive ?? isProcessAlive;
443
+ const db = getDb();
444
+ interface InterruptedHistoryRow {
445
+ id: number;
446
+ started_at: string | null;
447
+ owner_pid: number | null;
448
+ owner_host: string | null;
449
+ owner_started_at: string | null;
450
+ }
451
+ const rows = db
376
452
  .prepare(
377
- `UPDATE history SET
378
- status = 'error',
379
- error = CASE
380
- WHEN error IS NULL OR error = '' THEN 'Прервано (сбой/перезагрузка)'
381
- ELSE error
382
- END,
383
- finished_at = COALESCE(finished_at, ?),
384
- duration_ms = COALESCE(
385
- duration_ms,
386
- CAST((julianday(?) - julianday(started_at)) * 86400000 AS INTEGER)
387
- )
388
- WHERE finished_at IS NULL`,
453
+ `SELECT id, started_at, owner_pid, owner_host, owner_started_at
454
+ FROM history WHERE finished_at IS NULL`,
389
455
  )
390
- .run(now, now);
391
- return Number(result.changes) || 0;
456
+ .all() as unknown as InterruptedHistoryRow[];
457
+ const update = db.prepare(
458
+ `UPDATE history SET
459
+ status = 'error',
460
+ error = CASE
461
+ WHEN error IS NULL OR error = '' THEN 'Прервано (сбой/перезагрузка)'
462
+ ELSE error
463
+ END,
464
+ finished_at = COALESCE(finished_at, ?),
465
+ duration_ms = COALESCE(
466
+ duration_ms,
467
+ CAST((julianday(?) - julianday(started_at)) * 86400000 AS INTEGER)
468
+ )
469
+ WHERE id = ? AND finished_at IS NULL`,
470
+ );
471
+
472
+ let recovered = 0;
473
+ let keptAlive = 0;
474
+ withTransaction(() => {
475
+ for (const row of rows) {
476
+ const ownerPid = row.owner_pid == null ? null : Number(row.owner_pid);
477
+ const ownerHost = row.owner_host == null ? null : String(row.owner_host);
478
+ const verifiable =
479
+ ownerPid != null && ownerPid > 0 && ownerHost != null && ownerHost === hostname;
480
+
481
+ if (verifiable && ownerPid != null && isAlive(ownerPid)) {
482
+ keptAlive += 1;
483
+ continue;
484
+ }
485
+ if (!verifiable) {
486
+ const since = Date.parse(String(row.owner_started_at ?? row.started_at ?? ""));
487
+ const age = Number.isFinite(since) ? now.getTime() - since : Infinity;
488
+ if (age < maxAge) {
489
+ keptAlive += 1;
490
+ continue;
491
+ }
492
+ }
493
+
494
+ const result = update.run(nowIso, nowIso, row.id);
495
+ if (Number(result.changes) > 0) recovered += 1;
496
+ }
497
+ });
498
+ return { recovered, keptAlive };
392
499
  }
393
500
 
394
501
  /** Количество записей истории (для миграции и тестов). */
@@ -57,8 +57,8 @@ export function incrementMetricsUnsafe(
57
57
  tokens = 0,
58
58
  costUsd = 0,
59
59
  ): void {
60
- // error — только ошибки и таймауты; partial хранится отдельным счётчиком,
61
- // иначе дашборд показывал частичный запуск как обычную ошибку.
60
+ // error — только ошибки и таймауты; partial и skipped хранятся отдельно
61
+ // (skipped увеличивает только total: запуск не расходовал токены и не завершился).
62
62
  const success = status === "success" ? 1 : 0;
63
63
  const partial = status === "partial" ? 1 : 0;
64
64
  const error = status === "error" || status === "timeout" ? 1 : 0;
@@ -12,13 +12,14 @@ const JSON_FILES = ["tasks.json", "history.json", "metrics.json", "templates.jso
12
12
  * Вызывается при setup() до запуска catch-up и файловых триггеров.
13
13
  */
14
14
  export function recoverInterruptedRuns(): number {
15
- const count = recoverInterrupted();
16
- if (count > 0) {
15
+ const { recovered, keptAlive } = recoverInterrupted();
16
+ if (recovered > 0 || keptAlive > 0) {
17
17
  console.log(
18
- `[recovery] Восстановлено ${count} незавершённых записей истории — помечены как error.`,
18
+ `[recovery] Восстановлено ${recovered} незавершённых записей истории — помечены как error.` +
19
+ (keptAlive > 0 ? ` Оставлено живым владельцам: ${keptAlive}.` : ""),
19
20
  );
20
21
  }
21
- return count;
22
+ return recovered;
22
23
  }
23
24
 
24
25
  /**
@@ -1,14 +1,17 @@
1
+ import os from "node:os";
1
2
  import { getDb, withTransaction } from "./index.js";
2
3
  import {
3
4
  finishStep,
4
5
  getRun,
5
6
  getStep,
7
+ renewStepLease as renewStepLeaseRow,
6
8
  retryStep,
7
9
  startRun,
8
10
  startStep,
9
11
  type FinishOptions,
10
12
  type RunRecord,
11
13
  type RunStepRecord,
14
+ type StepLease,
12
15
  } from "./runs-repo.js";
13
16
 
14
17
  /**
@@ -23,10 +26,29 @@ import {
23
26
  /** Текст ошибки, которым помечается шаг, прерванный падением процесса. */
24
27
  export const STEP_INTERRUPTED_ERROR = "Прервано падением процесса";
25
28
 
29
+ /**
30
+ * B12: срок lease шага по умолчанию. Живой процесс продлевает lease
31
+ * (heartbeat в `runStepStatefullyAsync` или явный `renewStepLease`), поэтому
32
+ * recovery финализирует шаг только после истечения этого срока.
33
+ */
34
+ export const STEP_LEASE_MS = 60_000;
35
+
36
+ let cachedOwnerId: string | null = null;
37
+
38
+ /** B12: идентификатор текущего процесса — `host:pid:startedAt`. */
39
+ export function getStepOwnerId(): string {
40
+ if (!cachedOwnerId) {
41
+ cachedOwnerId = `${os.hostname()}:${process.pid}:${nowIso()}`;
42
+ }
43
+ return cachedOwnerId;
44
+ }
45
+
26
46
  /** Опции начала попытки. */
27
47
  export interface BeginStepOptions {
28
48
  /** Начать запуск, если он ещё в статусе pending (по умолчанию true). */
29
49
  startRun?: boolean;
50
+ /** B12: срок lease в миллисекундах (по умолчанию {@link STEP_LEASE_MS}). */
51
+ leaseMs?: number;
30
52
  }
31
53
 
32
54
  /** Результат выполнения шага через `runStepStatefully`. */
@@ -68,15 +90,41 @@ export function beginStepAttempt(
68
90
  }
69
91
 
70
92
  const step = requireStep(runId, stepName);
93
+ const lease = buildLease(options.leaseMs);
71
94
  if (step.status === "failed") {
72
- retryStep(step.id);
95
+ retryStep(step.id, undefined, lease);
73
96
  } else {
74
- startStep(step.id);
97
+ startStep(step.id, undefined, lease);
75
98
  }
76
99
 
77
100
  return requireStep(runId, stepName);
78
101
  }
79
102
 
103
+ /**
104
+ * B12: продлевает lease шага текущего процесса.
105
+ *
106
+ * Нужен долгим синхронным шагам: без продления recovery сочтёт шаг
107
+ * осиротевшим после {@link STEP_LEASE_MS}. Возвращает false, если шаг уже
108
+ * не `running`.
109
+ */
110
+ export function renewStepLease(
111
+ runId: string,
112
+ stepName: string,
113
+ leaseMs: number = STEP_LEASE_MS,
114
+ ): boolean {
115
+ const step = requireStep(runId, stepName);
116
+ if (step.status !== "running") return false;
117
+ return renewStepLeaseRow(step.id, buildLease(leaseMs));
118
+ }
119
+
120
+ function buildLease(leaseMs: number = STEP_LEASE_MS): StepLease {
121
+ const duration = Number.isFinite(leaseMs) && leaseMs > 0 ? leaseMs : STEP_LEASE_MS;
122
+ return {
123
+ ownerId: getStepOwnerId(),
124
+ leaseUntil: new Date(Date.now() + duration).toISOString(),
125
+ };
126
+ }
127
+
80
128
  /** Закрывает попытку успехом: running → passed, сохраняет output. */
81
129
  export function recordStepSuccess(
82
130
  runId: string,
@@ -127,39 +175,78 @@ export async function runStepStatefullyAsync<T>(
127
175
  body: () => Promise<T> | T,
128
176
  options: BeginStepOptions = {},
129
177
  ): Promise<StepExecution<T>> {
178
+ const leaseMs = options.leaseMs ?? STEP_LEASE_MS;
130
179
  const attempt = beginStepAttempt(runId, stepName, options).attempt;
180
+ // B12: heartbeat продлевает lease, пока тело шага реально выполняется.
181
+ const timer = setInterval(
182
+ () => {
183
+ try {
184
+ renewStepLease(runId, stepName, leaseMs);
185
+ } catch {
186
+ // Шаг уже финализирован — продлевать нечего.
187
+ }
188
+ },
189
+ Math.max(10, Math.floor(leaseMs / 3)),
190
+ );
191
+ timer.unref?.();
131
192
  let result: T;
132
193
  try {
133
- result = await body();
134
- } catch (err) {
135
- recordStepFailure(runId, stepName, err);
136
- throw err;
194
+ try {
195
+ result = await body();
196
+ } catch (err) {
197
+ recordStepFailure(runId, stepName, err);
198
+ throw err;
199
+ }
200
+ } finally {
201
+ clearInterval(timer);
137
202
  }
138
203
  const step = recordStepSuccess(runId, stepName, result);
139
204
  return { step, result, attempt };
140
205
  }
141
206
 
207
+ export interface RecoverStepsOptions {
208
+ /**
209
+ * B12: текущий момент для проверки lease. По умолчанию now; тесты и
210
+ * отложенный recovery передают «будущее», чтобы lease считался истёкшим.
211
+ */
212
+ now?: string | Date;
213
+ }
214
+
142
215
  /**
143
- * Помечает все зависшие `running`-шаги как failed, сохраняя `attempt`.
216
+ * Помечает осиротевшие `running`-шаги как failed, сохраняя `attempt`.
144
217
  *
145
- * Возвращает обновлённые записи. `attempt` не сбрасывается — следующая попытка
146
- * получит `attempt + 1` через `retryStep`, поэтому номер попытки переживает
147
- * падение процесса и восстановление.
218
+ * B12: шаг финализируется только при отсутствии lease (legacy-строки) или
219
+ * истёкшем `lease_until`. Шаг с живым lease принадлежит работающему процессу
220
+ * и не трогается. Возвращает обновлённые записи.
221
+ *
222
+ * `attempt` не сбрасывается — следующая попытка получит `attempt + 1` через
223
+ * `retryStep`, поэтому номер попытки переживает падение процесса и восстановление.
148
224
  */
149
- export function recoverInterruptedSteps(runId?: string): RunStepRecord[] {
225
+ export function recoverInterruptedSteps(
226
+ runId?: string,
227
+ options: RecoverStepsOptions = {},
228
+ ): RunStepRecord[] {
150
229
  const running = listRunningSteps(runId);
151
230
  if (running.length === 0) return [];
152
231
 
232
+ const nowMs = options.now ? new Date(options.now).getTime() : Date.now();
233
+ const expired = running.filter((step) => {
234
+ if (!step.leaseUntil) return true;
235
+ const until = Date.parse(step.leaseUntil);
236
+ return Number.isNaN(until) || until <= nowMs;
237
+ });
238
+ if (expired.length === 0) return [];
239
+
153
240
  return withTransaction(() => {
154
241
  const timestamp = nowIso();
155
242
  const update = getDb().prepare(
156
243
  `UPDATE run_steps SET status = 'failed', error = ?, finished_at = ?,
157
244
  updated_at = ? WHERE id = ? AND status = 'running'`,
158
245
  );
159
- for (const step of running) {
246
+ for (const step of expired) {
160
247
  update.run(STEP_INTERRUPTED_ERROR, timestamp, timestamp, step.id);
161
248
  }
162
- return running.map((step) => requireStep(step.runId, step.stepName));
249
+ return expired.map((step) => requireStep(step.runId, step.stepName));
163
250
  });
164
251
  }
165
252
 
@@ -8,6 +8,7 @@ import {
8
8
  type RunStepRecord,
9
9
  } from "./runs-repo.js";
10
10
  import {
11
+ listRunningSteps,
11
12
  recoverInterruptedSteps,
12
13
  requireRun,
13
14
  runStepStatefully,
@@ -38,6 +39,11 @@ export interface ResumeOptions {
38
39
  handlers: Record<string, StepHandler>;
39
40
  /** Восстанавливать зависшие `running`-шаги перед продолжением (по умолчанию true). */
40
41
  recover?: boolean;
42
+ /**
43
+ * B12: момент для проверки lease при восстановлении. По умолчанию now.
44
+ * Передавайте будущее время, чтобы считать lease зависшего шага истёкшим.
45
+ */
46
+ recoverNow?: string | Date;
41
47
  /** Останавливаться на первой ошибке (по умолчанию true). */
42
48
  stopOnError?: boolean;
43
49
  }
@@ -84,7 +90,17 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
84
90
  throw new Error(`Запуск отменён, возобновление невозможно: ${runId}`);
85
91
  }
86
92
 
87
- if (options.recover !== false) recoverInterruptedSteps(runId);
93
+ if (options.recover !== false) recoverInterruptedSteps(runId, { now: options.recoverNow });
94
+
95
+ // B12: шаг с живым lease принадлежит работающему процессу. Возобновлять его
96
+ // здесь нельзя — иначе два исполнителя возьмут один шаг.
97
+ const active = listRunningSteps(runId);
98
+ if (active.length > 0) {
99
+ const step = active[0];
100
+ throw new Error(
101
+ `Шаг ${step.stepName} выполняется другим процессом (lease до ${step.leaseUntil ?? "неизвестно"}); возобновление отложено.`,
102
+ );
103
+ }
88
104
 
89
105
  const steps = listRunSteps(runId);
90
106
  const startIndex = steps.findIndex((step) => !isStepDone(step.status));
@@ -79,7 +79,12 @@ export interface RunStepRecord {
79
79
  position: number;
80
80
  status: StepStatus;
81
81
  attempt: number;
82
+ /** Ключ идемпотентности (36.3); уникален в пределах запуска. */
82
83
  idempotencyKey: string | null;
84
+ /** B12: идентификатор процесса-владельца шага (`host:pid:startedAt`). */
85
+ ownerId: string | null;
86
+ /** B12: момент, до которого владелец обязан продлить lease (ISO). */
87
+ leaseUntil: string | null;
83
88
  startedAt: string | null;
84
89
  finishedAt: string | null;
85
90
  error: string | null;
@@ -115,6 +120,12 @@ export interface FinishOptions {
115
120
  output?: unknown;
116
121
  }
117
122
 
123
+ /** B12: владелец шага и срок его lease. */
124
+ export interface StepLease {
125
+ ownerId: string;
126
+ leaseUntil: string;
127
+ }
128
+
118
129
  function nowIso(): string {
119
130
  return new Date().toISOString();
120
131
  }
@@ -162,6 +173,8 @@ function stepRowToRecord(row: any): RunStepRecord {
162
173
  status: String(row.status) as StepStatus,
163
174
  attempt: Number(row.attempt) || 1,
164
175
  idempotencyKey: row.idempotency_key == null ? null : String(row.idempotency_key),
176
+ ownerId: row.owner_id == null ? null : String(row.owner_id),
177
+ leaseUntil: row.lease_until == null ? null : String(row.lease_until),
165
178
  startedAt: row.started_at == null ? null : String(row.started_at),
166
179
  finishedAt: row.finished_at == null ? null : String(row.finished_at),
167
180
  error: row.error == null ? null : String(row.error),
@@ -410,7 +423,7 @@ export function findStepByIdempotencyKey(
410
423
  }
411
424
 
412
425
  /** pending → running. Возвращает false, если шаг не найден. */
413
- export function startStep(id: string, startedAt = nowIso()): boolean {
426
+ export function startStep(id: string, startedAt = nowIso(), lease?: StepLease): boolean {
414
427
  return withTransaction(() => {
415
428
  const step = getStepById(id);
416
429
  if (!step) return false;
@@ -418,9 +431,9 @@ export function startStep(id: string, startedAt = nowIso()): boolean {
418
431
  getDb()
419
432
  .prepare(
420
433
  `UPDATE run_steps SET status = 'running', started_at = ?, finished_at = NULL,
421
- error = NULL, updated_at = ? WHERE id = ?`,
434
+ error = NULL, owner_id = ?, lease_until = ?, updated_at = ? WHERE id = ?`,
422
435
  )
423
- .run(startedAt, nowIso(), id);
436
+ .run(startedAt, lease?.ownerId ?? null, lease?.leaseUntil ?? null, nowIso(), id);
424
437
  return true;
425
438
  });
426
439
  }
@@ -459,7 +472,7 @@ export function finishStep(
459
472
  * Это единственный переход из финального статуса шага. Предыдущая попытка
460
473
  * остаётся видимой в счётчике attempt; для 36.4 (DLQ) здесь появится лимит.
461
474
  */
462
- export function retryStep(id: string, startedAt = nowIso()): boolean {
475
+ export function retryStep(id: string, startedAt = nowIso(), lease?: StepLease): boolean {
463
476
  return withTransaction(() => {
464
477
  const step = getStepById(id);
465
478
  if (!step) return false;
@@ -469,13 +482,30 @@ export function retryStep(id: string, startedAt = nowIso()): boolean {
469
482
  getDb()
470
483
  .prepare(
471
484
  `UPDATE run_steps SET status = 'running', attempt = attempt + 1,
472
- started_at = ?, finished_at = NULL, error = NULL, updated_at = ? WHERE id = ?`,
485
+ started_at = ?, finished_at = NULL, error = NULL,
486
+ owner_id = ?, lease_until = ?, updated_at = ? WHERE id = ?`,
473
487
  )
474
- .run(startedAt, nowIso(), id);
488
+ .run(startedAt, lease?.ownerId ?? null, lease?.leaseUntil ?? null, nowIso(), id);
475
489
  return true;
476
490
  });
477
491
  }
478
492
 
493
+ /**
494
+ * B12: продлевает lease выполняющегося шага.
495
+ *
496
+ * Возвращает false, если шаг уже не `running` (например, recovery успел
497
+ * финализировать его после истечения lease): продлевать нечего.
498
+ */
499
+ export function renewStepLease(id: string, lease: StepLease): boolean {
500
+ const result = getDb()
501
+ .prepare(
502
+ `UPDATE run_steps SET owner_id = ?, lease_until = ?, updated_at = ?
503
+ WHERE id = ? AND status = 'running'`,
504
+ )
505
+ .run(lease.ownerId, lease.leaseUntil, nowIso(), id);
506
+ return Number(result.changes) > 0;
507
+ }
508
+
479
509
  /** Количество шагов запуска (для health/отчётов). */
480
510
  export function countRunSteps(runId: string): number {
481
511
  const row = getDb()
package/src/db/schema.ts CHANGED
@@ -31,7 +31,12 @@ CREATE TABLE IF NOT EXISTS history (
31
31
  next_task TEXT,
32
32
  workspace_id TEXT,
33
33
  allowed_tools TEXT,
34
- denied_tools TEXT
34
+ denied_tools TEXT,
35
+ -- Схема v8: владелец незавершённого запуска. Нужен recovery, чтобы не
36
+ -- финализировать прогон, чей процесс ещё жив (B1).
37
+ owner_pid INTEGER,
38
+ owner_host TEXT,
39
+ owner_started_at TEXT
35
40
  );
36
41
 
37
42
  CREATE INDEX IF NOT EXISTS idx_history_task ON history(task_name, started_at DESC);
@@ -154,6 +159,10 @@ CREATE TABLE IF NOT EXISTS run_steps (
154
159
  status TEXT NOT NULL,
155
160
  attempt INTEGER NOT NULL DEFAULT 1,
156
161
  idempotency_key TEXT,
162
+ -- B12: владелец и lease шага. Живой процесс продлевает lease; recovery
163
+ -- финализирует только шаги с истёкшим lease, не трогая чужие живые.
164
+ owner_id TEXT,
165
+ lease_until TEXT,
157
166
  started_at TEXT,
158
167
  finished_at TEXT,
159
168
  error TEXT,
@@ -217,6 +226,7 @@ CREATE TABLE IF NOT EXISTS capability_map (
217
226
  model TEXT NOT NULL,
218
227
  runs_total INTEGER NOT NULL DEFAULT 0,
219
228
  runs_passed INTEGER NOT NULL DEFAULT 0,
229
+ first_pass_count INTEGER,
220
230
  success_rate REAL NOT NULL DEFAULT 0,
221
231
  avg_cost_usd REAL NOT NULL DEFAULT 0,
222
232
  avg_time_ms REAL NOT NULL DEFAULT 0,
@@ -241,7 +251,7 @@ interface SchemaDb {
241
251
  * миграций. Увеличивайте при добавлении новой ступени в {@link MIGRATIONS}
242
252
  * и добавляйте соответствующую запись в массив.
243
253
  */
244
- export const SCHEMA_VERSION = 7;
254
+ export const SCHEMA_VERSION = 10;
245
255
 
246
256
  /** Возвращает сохранённую версию схемы (0 у legacy-БД без user_version). */
247
257
  export function getSchemaVersion(db: SchemaDb): number {
@@ -461,6 +471,59 @@ const MIGRATIONS: { to: number; migrate: (db: SchemaDb) => void }[] = [
461
471
  `);
462
472
  },
463
473
  },
474
+ {
475
+ // Ступень 8 — владелец незавершённого запуска (B1). Recovery должен
476
+ // отличать живой прогон от осиротевшего: PID процесса-обёртки, метка
477
+ // хоста и время старта владельца. Колонки аддитивные, поэтому ступень
478
+ // идемпотентна и безопасна для старых БД.
479
+ to: 8,
480
+ migrate(db) {
481
+ const columnNames = tableColumns(db, "history");
482
+ if (!columnNames.includes("owner_pid")) {
483
+ db.exec("ALTER TABLE history ADD COLUMN owner_pid INTEGER");
484
+ }
485
+ if (!columnNames.includes("owner_host")) {
486
+ db.exec("ALTER TABLE history ADD COLUMN owner_host TEXT");
487
+ }
488
+ if (!columnNames.includes("owner_started_at")) {
489
+ db.exec("ALTER TABLE history ADD COLUMN owner_started_at TEXT");
490
+ }
491
+ },
492
+ },
493
+ {
494
+ // Ступень 9 — lease/владелец шага (B12). Recovery больше не убивает
495
+ // `running`-шаги вслепую: у шага есть owner_id и lease_until, а живой
496
+ // процесс продлевает lease. Колонки аддитивные — ступень идемпотентна.
497
+ to: 9,
498
+ migrate(db) {
499
+ const columnNames = tableColumns(db, "run_steps");
500
+ if (!columnNames.includes("owner_id")) {
501
+ db.exec("ALTER TABLE run_steps ADD COLUMN owner_id TEXT");
502
+ }
503
+ if (!columnNames.includes("lease_until")) {
504
+ db.exec("ALTER TABLE run_steps ADD COLUMN lease_until TEXT");
505
+ }
506
+ },
507
+ },
508
+ {
509
+ // Ступень 10 — first-pass статистика Capability Map (B13). Успех с первой
510
+ // попытки нельзя восстановить из runs_passed, поэтому для legacy-строк
511
+ // считаем все прошлые успехи первыми (first_pass_count = runs_passed).
512
+ // NULL отличает «не заполнено миграцией» от честного нуля.
513
+ to: 10,
514
+ migrate(db) {
515
+ const columnNames = tableColumns(db, "capability_map");
516
+ if (!columnNames.includes("first_pass_count")) {
517
+ db.exec("ALTER TABLE capability_map ADD COLUMN first_pass_count INTEGER");
518
+ }
519
+ const columnsAfter = tableColumns(db, "capability_map");
520
+ if (columnsAfter.includes("first_pass_count")) {
521
+ db.exec(
522
+ "UPDATE capability_map SET first_pass_count = runs_passed WHERE first_pass_count IS NULL",
523
+ );
524
+ }
525
+ },
526
+ },
464
527
  ];
465
528
 
466
529
  /** Имена колонок таблицы (пустой массив, если таблицы нет). */