@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{prd-store.js → planning/prd-store.js}

@@ -1,4 +1,4 @@
-// engine/prd-store.js
+// engine/planning/prd-store.js
 //
 // SQL-authoritative PRD state.
 
@@ -192,11 +192,11 @@ function writePrd(filename, prd, { archived = false } = {}) {
     throw new TypeError('prd-store.writePrd requires a filename and object');
   }
   const normalizedPrd = _normalizePrdForStorage(prd);
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const archivedValue = archived ? 1 : 0;
   const prdId = withTransaction(db, () => _upsertPrd(db, filename, archivedValue, normalizedPrd, Date.now()));
-  require('./db-events').emitStateEvent('prds', { filename, archived: archivedValue });
+  require('../persistence/db-events').emitStateEvent('prds', { filename, archived: archivedValue });
   return { ok: true, id: prdId, plan: normalizedPrd };
 }
 
@@ -207,7 +207,7 @@ function createPrdUnique(baseFilename, prd) {
   }
   const normalizedPrd = _normalizePrdForStorage(prd);
   const stem = baseFilename.slice(0, -'.json'.length);
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const filename = withTransaction(db, () => {
     const exists = db.prepare('SELECT 1 FROM prds WHERE filename=? LIMIT 1');
@@ -219,7 +219,7 @@ function createPrdUnique(baseFilename, prd) {
     }
     throw new Error('Could not reserve unique PRD filename after 100 attempts');
   });
-  require('./db-events').emitStateEvent('prds', { filename, archived: 0 });
+  require('../persistence/db-events').emitStateEvent('prds', { filename, archived: 0 });
   return filename;
 }
 
@@ -228,7 +228,7 @@ function mutatePrd(filename, mutator, { archived = false, defaultValue = {} } =
   if (typeof mutator !== 'function') {
     throw new TypeError('prd-store.mutatePrd requires a filename and mutator');
   }
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const result = withTransaction(db, () => {
     const archivedValue = archived ? 1 : 0;
@@ -244,13 +244,13 @@ function mutatePrd(filename, mutator, { archived = false, defaultValue = {} } =
     _upsertPrd(db, filename, archivedValue, normalizedPrd, Date.now());
     return normalizedPrd;
   });
-  require('./db-events').emitStateEvent('prds', { filename, archived: archived ? 1 : 0 });
+  require('../persistence/db-events').emitStateEvent('prds', { filename, archived: archived ? 1 : 0 });
   return result;
 }
 
 function deletePrd(filename, { archived = false } = {}) {
   validatePrdFilename(filename);
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const removed = withTransaction(db, () => {
     const archivedValue = archived ? 1 : 0;
@@ -259,13 +259,13 @@ function deletePrd(filename, { archived = false } = {}) {
     _deletePrdRow(db, row.id);
     return true;
   });
-  if (removed) require('./db-events').emitStateEvent('prds', { filename, archived: archived ? 1 : 0, removed: true });
+  if (removed) require('../persistence/db-events').emitStateEvent('prds', { filename, archived: archived ? 1 : 0, removed: true });
   return removed;
 }
 
 function readPrd(filename, { archived = false } = {}) {
   validatePrdFilename(filename);
-  const row = require('./db').getDb()
+  const row = require('../db').getDb()
     .prepare('SELECT data FROM prds WHERE filename=? AND archived=?')
     .get(filename, archived ? 1 : 0);
   return row ? JSON.parse(row.data) : null;
@@ -284,7 +284,7 @@ function restorePrdFromArchive(filename) {
   if (!filename || typeof filename !== 'string') {
     throw new TypeError('prd-store.restorePrdFromArchive requires a filename');
   }
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const restored = withTransaction(db, () => {
     const row = db.prepare('SELECT id, data FROM prds WHERE filename=? AND archived=1').get(filename);
@@ -295,7 +295,7 @@ function restorePrdFromArchive(filename) {
     return prd;
   });
   if (restored) {
-    require('./db-events').emitStateEvent('prds', { filename, archived: 0, restored: true });
+    require('../persistence/db-events').emitStateEvent('prds', { filename, archived: 0, restored: true });
   }
   return restored;
 }
@@ -309,7 +309,7 @@ function movePrdToArchive(filename, replacementPrd) {
       && (!replacementPrd || typeof replacementPrd !== 'object' || Array.isArray(replacementPrd))) {
     throw new TypeError('prd-store.movePrdToArchive replacement must be a PRD object');
   }
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const archived = withTransaction(db, () => {
     const row = db.prepare('SELECT id, data FROM prds WHERE filename=? AND archived=0').get(filename);
@@ -322,7 +322,7 @@ function movePrdToArchive(filename, replacementPrd) {
     return prd;
   });
   if (archived) {
-    require('./db-events').emitStateEvent('prds', {
+    require('../persistence/db-events').emitStateEvent('prds', {
       filename,
       archived: 1,
       compensated: true,
@@ -338,9 +338,9 @@ function movePrdToArchive(filename, replacementPrd) {
 // Returns { ok, byWorkItemId, bySourcePlan } counts.
 function backfillWorkItemPrdItemIds() {
   let db;
-  try { db = require('./db').getDb(); } catch { return { ok: false }; }
+  try { db = require('../db').getDb(); } catch { return { ok: false }; }
   try {
-    return require('./db').withTransaction(db, () => {
+    return require('../db').withTransaction(db, () => {
       // Path 1 — explicit prd_items.work_item_id backref (most precise).
       const r1 = db.prepare(`
         UPDATE work_items SET prd_item_id = (
@@ -378,7 +378,7 @@ function backfillWorkItemPrdItemIds() {
 // data blob. Sorted by (archived, filename) for deterministic consumer order
 // (matches the disk-scan order once the caller also sorts). Read-flip source.
 function listPrdRows() {
-  const db = require('./db').getDb();
+  const db = require('../db').getDb();
   const rows = db.prepare('SELECT filename, archived, data, updated_at FROM prds ORDER BY archived, filename').all();
   const out = [];
   for (const r of rows) {

package/engine/{project-discovery.js → planning/project-discovery.js}

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync: defaultExecFileSync } = require('child_process');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 function decodeUrlSegment(segment) {
   try { return decodeURIComponent(String(segment || '')); } catch { return String(segment || ''); }
@@ -196,7 +196,7 @@ function runAzJson(execFileSync, args, timeoutMs) {
 }
 
 // W-mq8li79a000889fa — official ADO REST endpoint for repo lookup.
-// Matches engine/ado.js#resolveAdoBuildRepositoryGuid (the canonical
+// Matches engine/ado/index.js#resolveAdoBuildRepositoryGuid (the canonical
 // PR-poll path). Path-style encoding mirrors that helper so a project
 // named with reserved chars (e.g. "Project With Spaces") routes the
 // same way at link time as at poll time. The repo segment is URL-
@@ -212,7 +212,7 @@ function _buildAdoRepoLookupUrl({ orgUrl, project, repoName }) {
 // this AFTER `az repos show/list` to fill in the GUID when the CLI is
 // unavailable (typical agent box without Azure CLI installed).
 //
-// Token acquisition uses engine/ado-token.js#acquireAdoToken (az CLI
+// Token acquisition uses engine/ado/token.js#acquireAdoToken (az CLI
 // then azureauth fallback). Tests inject `options.fetch` and
 // `options.acquireAdoToken` directly.
 async function resolveAdoRemoteMetadataViaRest(remote, options = {}) {
@@ -221,7 +221,7 @@ async function resolveAdoRemoteMetadataViaRest(remote, options = {}) {
   if (typeof fetchImpl !== 'function') return null;
   let acquireToken = options.acquireAdoToken;
   if (typeof acquireToken !== 'function') {
-    try { acquireToken = require('./ado-token').acquireAdoToken; }
+    try { acquireToken = require('../ado/token').acquireAdoToken; }
     catch { return null; }
   }
   let token;
@@ -387,7 +387,7 @@ function discoverProjectMetadata(targetDir, options = {}) {
 
 // W-mq8li79a000889fa — async wrapper that runs the sync `az`-based
 // discovery first, then falls back to the official ADO REST endpoint
-// (via engine/ado-token.js + globalThis.fetch) when the remote is ADO
+// (via engine/ado/token.js + globalThis.fetch) when the remote is ADO
 // but no repositoryId was resolved. Non-ADO remotes are returned
 // unchanged. Failure to resolve the GUID via REST leaves
 // `repositoryId` empty — callers (engine/projects.js#addProject) MUST

package/engine/{projects.js → planning/projects.js}

@@ -7,12 +7,12 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const dispatch = require('./dispatch');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const dispatch = require('../orchestration/dispatch');
+const queries = require('../core/queries');
 const projectDiscovery = require('./project-discovery');
-const scheduleBootstrap = require('./schedule-bootstrap');
-const apiValidation = require('./api-validation');
+const scheduleBootstrap = require('../orchestration/schedule-bootstrap');
+const apiValidation = require('../api/api-validation');
 const { MINIONS_DIR } = shared;
 
 const PROJECT_PATH_MAX_LENGTH = 4096;
@@ -195,7 +195,7 @@ function resolveProjectRemovalDataMode(options = {}) {
 // Windows EPERM/EBUSY can hit fs.renameSync transiently when antivirus,
 // indexer, or another scanner has the directory open. Retry with backoff
 // before giving up — same pattern used by shared.safeWrite for atomic
-// JSON writes (engine/shared.js:424).
+// JSON writes (engine/core/shared.js:424).
 function _renameWithRetry(src, dest) {
   for (let attempt = 0; attempt < 5; attempt++) {
     try {
@@ -377,7 +377,7 @@ function removeProject(target, options = {}) {
   //      Kills + unlinks every spec owned by this project, including the .log
   //      and .log.1 rotated sibling. Best-effort: failures only warn.
   try {
-    const managedSpawn = require('./managed-spawn');
+    const managedSpawn = require('../processes/managed-spawn');
     const result = managedSpawn.removeManagedSpecsForProject(project.name);
     summary.killedManagedProcesses = result.killed || 0;
   } catch (e) {
@@ -423,7 +423,7 @@ function removeProject(target, options = {}) {
   const archivedSourcePlans = new Set();
   try {
     {
-      const { archivePlan } = require('./lifecycle');
+      const { archivePlan } = require('../orchestration/lifecycle');
       for (const { filename: f, plan: prd, archived } of require('./prd-store').listPrdRows()) {
         if (archived) continue;
         try {
@@ -458,7 +458,7 @@ function removeProject(target, options = {}) {
   // 6. Surface pipelines that reference this project so the user can review
   //    them. Don't auto-modify — user intent there is unclear.
   try {
-    const { getPipelines } = require('./pipeline');
+    const { getPipelines } = require('../orchestration/pipeline');
     for (const p of getPipelines() || []) {
       const refs = [
         ...(p.monitoredResources || []),
@@ -602,7 +602,7 @@ function removeProject(target, options = {}) {
 
   // 9. Drop SQL rows for the removed project scope.
   try { require('./work-items-store').dropScope(project.name); } catch { /* best-effort */ }
-  try { require('./pull-requests-store').dropScope(project.name); } catch { /* best-effort */ }
+  try { require('../persistence/pull-requests-store').dropScope(project.name); } catch { /* best-effort */ }
 
   summary.ok = true;
   return summary;

package/engine/{resolve-area.js → planning/resolve-area.js}

@@ -1,5 +1,5 @@
 /**
- * engine/resolve-area.js — Reverse "component name → subproject path" resolver.
+ * engine/planning/resolve-area.js — Reverse component-to-path resolver.
  *
  * WI W-mrpbsbs7000ce8ac. Command Center (and other callers) frequently receive
  * a monorepo component name in a natural-language request ("audit OCM changes",

package/engine/{work-item-validation.js → planning/work-item-validation.js}

@@ -1,4 +1,4 @@
-const apiValidation = require('./api-validation');
+const apiValidation = require('../api/api-validation');
 
 const WORK_ITEM_SCOPES = Object.freeze(['fan-out']);
 const WORK_ITEM_FEEDBACK_RATINGS = Object.freeze(['up', 'down']);
@@ -323,6 +323,21 @@ function _normalizeWorkdir(value, field, validateWorkdir) {
   return result.value;
 }
 
+function _normalizeExecutionSurface(value, resolvedType, validateExecutionSurface) {
+  if (typeof validateExecutionSurface !== 'function') {
+    throw new TypeError('normalize work-item input requires validateExecutionSurface');
+  }
+  const result = validateExecutionSurface(value, resolvedType);
+  if (!result || result.valid !== true) {
+    _inputError(`meta.executionSurface: ${result?.error || 'invalid execution surface'}`, {
+      code: result?.code || 'invalid-execution-surface',
+      field: 'meta.executionSurface',
+      rejectedValue: value,
+    });
+  }
+  return result.value;
+}
+
 function _normalizeMeta(value, options = {}) {
   if (value === undefined) return undefined;
   apiValidation.validatePlainObject(value, {
@@ -341,6 +356,20 @@ function _normalizeMeta(value, options = {}) {
     if (workdir === null) delete normalized.workdir;
     else normalized.workdir = workdir;
   }
+  // W-ms5tb6ha016fda10 — explicit control-plane opt-in, validated fail-closed
+  // against the resolved work type. An ineligible (repo-reading/mutating) type
+  // is REJECTED at the API boundary rather than silently downgraded, so an
+  // operator cannot accidentally strip a checkout from work that needs one.
+  // The default 'repo' value is dropped so unchanged items keep today's shape.
+  if (_hasOwn(value, 'executionSurface')) {
+    const surface = _normalizeExecutionSurface(
+      value.executionSurface,
+      options.resolvedType,
+      options.validateExecutionSurface,
+    );
+    if (!surface || surface === 'repo') delete normalized.executionSurface;
+    else normalized.executionSurface = surface;
+  }
   for (const field of META_BOOLEAN_FIELDS) {
     if (_hasOwn(value, field)) {
       normalized[field] = _normalizeBoolean(value[field], `meta.${field}`);
@@ -445,7 +474,7 @@ function normalizeCreateInput(body, options = {}) {
   for (const field of ['skipPr', 'oneShot', 'agentLock', 'hardAgent']) {
     if (_hasOwn(body, field)) normalized[field] = _normalizeBoolean(body[field], field);
   }
-  normalized.meta = _normalizeMeta(body.meta, options);
+  normalized.meta = _normalizeMeta(body.meta, { ...options, resolvedType: normalized.type });
   for (const field of ['planFile', 'branch', 'branchStrategy', 'featureBranch']) {
     if (_hasOwn(body, field)) {
       normalized[field] = _normalizeText(body[field], field, {
@@ -510,7 +539,14 @@ function normalizeUpdateInput(body, options = {}) {
   if (_hasOwn(body, 'workdir')) {
     normalized.workdir = _normalizeWorkdir(body.workdir, 'workdir', options.validateWorkdir);
   }
-  normalized.meta = _normalizeMeta(body.meta, options);
+  // W-ms5tb6ha016fda10 — an update may change type, meta.executionSurface, or
+  // both. Prefer the incoming type; fall back to the stored item's type
+  // (`options.currentType`, supplied by the dashboard handler) so a
+  // meta-only edit is still checked against the type the item will run as.
+  normalized.meta = _normalizeMeta(body.meta, {
+    ...options,
+    resolvedType: _hasOwn(body, 'type') ? normalized.type : options.currentType,
+  });
   return normalized;
 }
 

package/engine/{work-items-store.js → planning/work-items-store.js}

@@ -1,4 +1,4 @@
-// engine/work-items-store.js — SQL-backed scoped work-item storage.
+// engine/planning/work-items-store.js — SQL-backed scoped work-item storage.
 //
 //   readWorkItemsForScope(scope)        -> [wi, wi, ...]
 //   applyWorkItemsMutation(scope, fn)   -> runs fn against the array,
@@ -22,7 +22,7 @@ function _parseRow(row) {
 }
 
 function readWorkItemsForScope(scope) {
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   const db = getDb();
 
   const rows = db.prepare(`
@@ -43,16 +43,24 @@ function readWorkItemsForScope(scope) {
 // needs to surface central + every project's items in a single shot,
 // tagged with their source scope.
 function readAllWorkItems() {
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   const db = getDb();
 
-  const rows = db.prepare('SELECT data, scope FROM work_items WHERE archived = 0 ORDER BY rowid').all();
+  const rows = db.prepare('SELECT data, scope, updated_at FROM work_items WHERE archived = 0 ORDER BY rowid').all();
   const out = [];
   for (const row of rows) {
     const wi = _parseRow(row);
     if (!wi) continue;
     // Preserve the legacy `_source` convention from queries.getWorkItems.
     wi._source = row.scope;
+    // Surface the authoritative last-mutation time (updated_at column, ms epoch)
+    // as an ISO `updatedAt` so /api/work-items consumers can sort on real
+    // last-updated rather than faking it from created/dispatched_at. The column
+    // wins over any stale in-blob value. (W-ms7kutzv003q17ad)
+    if (row.updated_at != null) {
+      const ms = Number(row.updated_at);
+      if (Number.isFinite(ms)) wi.updatedAt = new Date(ms).toISOString();
+    }
     out.push(wi);
   }
   return out;
@@ -136,7 +144,7 @@ function _applyWorkItemsDiff(db, diff) {
 //   result — the post-mutation array (legacy return shape of
 //            mutateJsonFileLocked)
 function applyWorkItemsMutation(scope, mutator, opts = {}) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
 
   return withTransaction(db, () => {
@@ -170,17 +178,17 @@ function applyWorkItemsMutation(scope, mutator, opts = {}) {
 // applyWorkItemsMutation's callers (see shared.js mutateWorkItems).
 function dropScope(scope) {
   try {
-    const { getDb } = require('./db');
+    const { getDb } = require('../db');
     const result = getDb().prepare('DELETE FROM work_items WHERE scope = ?').run(scope);
     if (result && result.changes > 0) {
-      try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-      try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+      try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+      try { require('../core/queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
     }
   } catch { /* db unavailable */ }
 }
 
 function readArchivedWorkItemsForScope(scope) {
-  const rows = require('./db').getDb().prepare(`
+  const rows = require('../db').getDb().prepare(`
     SELECT data FROM work_items
     WHERE scope = ? AND archived = 1
     ORDER BY updated_at DESC, rowid DESC
@@ -194,7 +202,7 @@ function readArchivedWorkItemsForScope(scope) {
 }
 
 function archiveWorkItem(scope, id, opts = {}) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const archived = withTransaction(db, () => {
     const row = db.prepare('SELECT data FROM work_items WHERE scope=? AND id=? AND archived=0').get(scope, String(id));
@@ -219,14 +227,14 @@ function archiveWorkItem(scope, id, opts = {}) {
     return item;
   });
   if (archived) {
-    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+    try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('../core/queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
   }
   return archived;
 }
 
 function replaceArchivedWorkItems(scope, items) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const count = withTransaction(db, () => {
     db.prepare('DELETE FROM work_items WHERE scope=? AND archived=1').run(scope);
@@ -257,13 +265,13 @@ function replaceArchivedWorkItems(scope, items) {
     }
     return inserted;
   });
-  try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-  try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+  try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+  try { require('../core/queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
   return count;
 }
 
 function moveWorkItem(sourceScope, targetScope, id, item) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const moved = withTransaction(db, () => {
     const source = db.prepare('SELECT 1 FROM work_items WHERE scope=? AND id=? AND archived=0')
@@ -292,15 +300,15 @@ function moveWorkItem(sourceScope, targetScope, id, item) {
     return Number(result.changes) > 0;
   });
   if (moved) {
-    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+    try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('../core/queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
   }
   return moved;
 }
 
 function moveWorkItemWithUpdate(sourceScope, targetScope, id, updater) {
   if (typeof updater !== 'function') throw new TypeError('moveWorkItemWithUpdate requires an updater');
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   const db = getDb();
   const outcome = withTransaction(db, () => {
     const source = db.prepare(
@@ -340,8 +348,8 @@ function moveWorkItemWithUpdate(sourceScope, targetScope, id, updater) {
     return { moved: true, reason: null, item: updated };
   });
   if (outcome.moved) {
-    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+    try { require('../persistence/db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('../core/queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
   }
   return outcome;
 }

package/engine/{keep-process-sweep.js → processes/keep-process-sweep.js}

@@ -1,5 +1,5 @@
 /**
- * engine/keep-process-sweep.js -- opt-in `meta.keep_processes` reaper.
+ * engine/processes/keep-process-sweep.js -- opt-in `meta.keep_processes` reaper.
  *
  * Walks agents/<id>/keep-pids.json files and, for each:
  *   - Validates the file (bounded JSON shape, see validateKeepPidsRecord).
@@ -19,8 +19,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 const processUtils = require('./process-utils');
 
 const { log, ENGINE_DEFAULTS } = shared;
@@ -262,14 +262,16 @@ function readKeepPidsFile(agentId, opts) {
   let raw;
   try { raw = fs.readFileSync(filePath, 'utf8'); }
   catch (_e) { return null; }
+  let mtimeMs = 0;
+  try { mtimeMs = fs.statSync(filePath).mtimeMs; } catch {}
   let parsed = null;
   try { parsed = JSON.parse(raw); }
   catch (e) {
-    return { agentId: agentId, filePath: filePath, valid: false, reason: 'json-parse: ' + e.message, parsed: null };
+    return { agentId: agentId, filePath: filePath, mtimeMs, valid: false, reason: 'json-parse: ' + e.message, parsed: null };
   }
   const v = validateKeepPidsRecord(parsed, opts);
-  if (!v.ok) return { agentId: agentId, filePath: filePath, valid: false, reason: v.reason, parsed: parsed };
-  return { agentId: agentId, filePath: filePath, valid: true, value: v.value, parsed: parsed };
+  if (!v.ok) return { agentId: agentId, filePath: filePath, mtimeMs, valid: false, reason: v.reason, parsed: parsed };
+  return { agentId: agentId, filePath: filePath, mtimeMs, valid: true, value: v.value, parsed: parsed };
 }
 
 function listAllKeepPidsFiles(opts) {
@@ -305,12 +307,28 @@ function _audit(eventType, payload) {
   } catch (_e) { /* logging best-effort */ }
 }
 
+function _identityMatchesDeclaration(rec, pid, opts) {
+  const getIdentity = typeof opts.getIdentity === 'function'
+    ? opts.getIdentity
+    : getKeepProcessIdentity;
+  let identity = null;
+  try { identity = getIdentity(pid, opts); } catch {}
+  return isKeepProcessIdentityCompatible(identity, rec.mtimeMs);
+}
+
+function _withIdentitySnapshot(opts) {
+  if (typeof opts.getIdentity === 'function' || Array.isArray(opts.processes)) return opts;
+  return { ...opts, processes: processUtils.listAllProcesses() };
+}
+
 function sweepKeepProcesses(opts) {
   opts = opts || {};
   const now = Number.isFinite(opts.now) ? opts.now : Date.now();
   const killOne = typeof opts.killOne === 'function'
     ? opts.killOne
-    : function (pid) { return shared.killByPidImmediate(pid); };
+    : function (pid, proof) {
+        return shared.terminateProcess('engine.keep-process.ttl', pid, proof);
+      };
   const stats = { scanned: 0, expiredFiles: 0, killedPids: 0, deadFiles: 0, malformed: 0 };
   // W-mp6k7ywi000fa33c — sweep ignores workdir validation so TTL/dead-PID
   // cleanup still drains files whose cwd no longer exists (e.g., the agent
@@ -318,6 +336,7 @@ function sweepKeepProcesses(opts) {
   // getActiveAnchorPids*) keep the default-on validation so invalid records
   // are not honored as anchors.
   const records = listAllKeepPidsFiles({ now: now, requireGitWorkdir: false });
+  if (records.length > 0) opts = _withIdentitySnapshot(opts);
   for (const rec of records) {
     stats.scanned++;
     if (!rec.valid) {
@@ -328,20 +347,30 @@ function sweepKeepProcesses(opts) {
     const value = rec.value;
     const filePath = rec.filePath;
     const agentId = rec.agentId;
+    const killDeclaredPid = (pid, reason) => {
+      if (!_identityMatchesDeclaration(rec, pid, opts)) {
+        _audit('identity-mismatch-skip', { agentId, pid, reason, wi_id: value.wi_id });
+        return false;
+      }
+      return killOne(pid, {
+        recordedAtMs: rec.mtimeMs,
+        skewMs: KEEP_PROCESS_IDENTITY_CLOCK_SKEW_MS,
+      });
+    };
     const executionContext = validateKeepProcessExecutionContext(value, opts);
     if (!executionContext.ok) {
       for (const pid of value.pids) {
-        if (killOne(pid)) stats.killedPids++;
-        _audit('unsafe-context-kill', { agentId, pid, reason: executionContext.reason, wi_id: value.wi_id });
+        _audit('unsafe-context-skip', { agentId, pid, reason: executionContext.reason, wi_id: value.wi_id });
       }
       try { fs.unlinkSync(filePath); } catch {}
-      log('warn', 'keep-processes: removed unsafe execution context for ' + agentId + ' — ' + executionContext.reason);
+      log('warn', 'keep-processes: removed unsafe execution context without trusting its PIDs for ' +
+        agentId + ' — ' + executionContext.reason);
       continue;
     }
     if (value.expiresAtMs < now) {
       let killed = 0;
       for (const pid of value.pids) {
-        const ok = killOne(pid);
+        const ok = killDeclaredPid(pid, 'ttl_expired');
         if (ok) killed++;
         _audit('ttl-expired-kill', { agentId: agentId, pid: pid, reason: 'ttl_expired', wi_id: value.wi_id });
       }
@@ -350,7 +379,8 @@ function sweepKeepProcesses(opts) {
       try { fs.unlinkSync(filePath); } catch (_e) { /* gone already */ }
       continue;
     }
-    const stillAlive = alivePids(value.pids, opts);
+    const stillAlive = alivePids(value.pids, opts)
+      .filter(pid => _identityMatchesDeclaration(rec, pid, opts));
     if (stillAlive.length === 0) {
       stats.deadFiles++;
       try { fs.unlinkSync(filePath); } catch (_e) { /* gone already */ }
@@ -364,11 +394,15 @@ function getActiveAnchorPids(opts) {
   opts = opts || {};
   const now = Number.isFinite(opts.now) ? opts.now : Date.now();
   const out = new Set();
-  for (const rec of listAllKeepPidsFiles({ now: now })) {
+  const records = listAllKeepPidsFiles({ now: now });
+  if (records.length > 0) opts = _withIdentitySnapshot(opts);
+  for (const rec of records) {
     if (!rec.valid) continue;
     if (rec.value.expiresAtMs < now) continue;
     if (!validateKeepProcessExecutionContext(rec.value, opts).ok) continue;
-    for (const pid of rec.value.pids) out.add(pid);
+    for (const pid of rec.value.pids) {
+      if (_identityMatchesDeclaration(rec, pid, opts)) out.add(pid);
+    }
   }
   return out;
 }
@@ -388,7 +422,10 @@ function getActiveAnchorPidsForAgent(agentId, opts) {
   if (rec.value.expiresAtMs < now) return { pids: out, record: rec.value, reason: 'expired' };
   const executionContext = validateKeepProcessExecutionContext(rec.value, opts);
   if (!executionContext.ok) return { pids: out, record: rec.value, reason: executionContext.reason };
-  for (const pid of rec.value.pids) out.add(pid);
+  opts = _withIdentitySnapshot(opts);
+  for (const pid of rec.value.pids) {
+    if (_identityMatchesDeclaration(rec, pid, opts)) out.add(pid);
+  }
   return { pids: out, record: rec.value };
 }
 
@@ -396,10 +433,13 @@ function getActiveKeepProcessCwds(opts) {
   opts = opts || {};
   const now = Number.isFinite(opts.now) ? opts.now : Date.now();
   const out = [];
-  for (const rec of listAllKeepPidsFiles({ now })) {
+  const records = listAllKeepPidsFiles({ now });
+  if (records.length > 0) opts = _withIdentitySnapshot(opts);
+  for (const rec of records) {
     if (!rec.valid || rec.value.expiresAtMs < now || !rec.value.cwd) continue;
     if (!validateKeepProcessExecutionContext(rec.value, opts).ok) continue;
-    if (alivePids(rec.value.pids, opts).length === 0) continue;
+    if (!alivePids(rec.value.pids, opts)
+      .some(pid => _identityMatchesDeclaration(rec, pid, opts))) continue;
     try { out.push(shared.realPathForComparison(rec.value.cwd)); }
     catch { /* malformed/unreachable cwd contributes no anchor */ }
   }

package/engine/{managed-spawn-launcher.js → processes/managed-spawn-launcher.js}

@@ -2,6 +2,7 @@
 'use strict';
 
 const { spawn } = require('child_process');
+const { terminateProcess } = require('./process-utils');
 
 const [cmd, ...args] = process.argv.slice(2);
 if (!cmd) {
@@ -37,10 +38,9 @@ if (!cmd) {
       console.error('[managed-spawn-launcher] target exited (code='
         + (code == null ? 'null' : code) + ', signal=' + (signal || 'null') + ')');
       if (signal) {
-        try {
-          process.kill(process.pid, signal);
+        if (terminateProcess('engine.managed-launcher.self-signal', { pid: process.pid }, { signal })) {
           return;
-        } catch {
+        } else {
           process.exitCode = 1;
           return;
         }