@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/db/migrations/027-review-learning-lifecycle.js

@@ -0,0 +1,162 @@
+// Review-learning lifecycle fields extend migration 017 in place. Existing
+// memory rows and FTS content stay intact; only exact generated feedback
+// provenance is moved out of the recallable `active` state.
+
+function _hasColumn(db, table, column) {
+  return db.prepare(`PRAGMA table_info(${table})`).all().some(row => row.name === column);
+}
+
+function _addColumn(db, table, definition) {
+  const column = definition.trim().split(/\s+/, 1)[0];
+  if (!_hasColumn(db, table, column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${definition}`);
+}
+
+function _parseObject(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// Mirror engine/review-learning.js#normalizeCanonicalPrId's space-compatible
+// contract so the quarantine accepts valid canonical IDs whose ADO
+// org/project/repo segments contain spaces (or %20) — createReviewFeedbackForAuthor
+// writes the raw canonical `pr.id`, and valid ADO scopes may contain spaces.
+// Kept self-contained: migrations must not import runtime engine modules.
+function _isCanonicalPrId(value) {
+  const match = String(value == null ? '' : value).trim().match(/^(github|ado):(.+?)#([1-9]\d*)$/i);
+  if (!match) return false;
+  const host = match[1].toLowerCase();
+  const expectedSegments = host === 'github' ? 2 : 3;
+  const segments = match[2]
+    .split('/')
+    .map(segment => segment.replace(/%20/gi, ' ').trim().toLowerCase());
+  if (segments.length !== expectedSegments) return false;
+  return segments.every(segment => (
+    segment
+    && !/[|#\u0000-\u001f\u007f]/.test(segment)
+    && (host !== 'github' || /^[a-z0-9][a-z0-9._-]*$/.test(segment))
+  ));
+}
+
+function _frontmatterBlocks(body) {
+  const blocks = [];
+  const re = /^---\r?\n([\s\S]*?)\r?\n---/gm;
+  let match;
+  while ((match = re.exec(String(body || ''))) !== null) {
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+      const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+      if (field) fields[field[1].toLowerCase()] = field[2].trim();
+    }
+    blocks.push(fields);
+  }
+  return blocks;
+}
+
+function _generatedFeedbackProvenance(row) {
+  if (row.source_type !== 'knowledge-base' || row.status !== 'active') return null;
+  if (!/^knowledge\/.+\.md$/i.test(String(row.source_path || ''))) return null;
+
+  const metadata = _parseObject(row.metadata);
+  const blocks = _frontmatterBlocks(row.body);
+  const sourceBlock = blocks.find(block => block.source && block.agent);
+  const detailBlock = blocks.find(block => block.sourcepr && block.reviewer && block.author);
+  if (!sourceBlock) return null;
+  if (String(sourceBlock.agent).toLowerCase() !== 'feedback') return null;
+  if (metadata.agent != null && String(metadata.agent).toLowerCase() !== 'feedback') return null;
+
+  const sourceRef = String(sourceBlock.source || '').trim();
+  if (!/^feedback-[a-z][a-z0-9-]{1,63}-from-[a-z][a-z0-9-]{1,63}-.+-\d{4}-\d{2}-\d{2}\.md$/.test(sourceRef)) {
+    return null;
+  }
+  if (detailBlock) {
+    const author = String(detailBlock.author || '').trim().toLowerCase();
+    const reviewer = String(detailBlock.reviewer || '').trim().toLowerCase();
+    if (String(detailBlock.agent || 'feedback').toLowerCase() !== 'feedback') return null;
+    if (!/^[a-z][a-z0-9-]{1,63}$/.test(author) || !/^[a-z][a-z0-9-]{1,63}$/.test(reviewer)) return null;
+    if (!sourceRef.startsWith(`feedback-${author}-from-${reviewer}-`)) return null;
+    if (!_isCanonicalPrId(detailBlock.sourcepr)) return null;
+  }
+  if (metadata.inbox != null && String(metadata.inbox) !== sourceRef) return null;
+  if (row.source_ref !== sourceRef && row.source_ref !== row.source_path) return null;
+  if (!/^# Review Feedback for .+/m.test(String(row.body || ''))) return null;
+  return { metadata, sourceRef };
+}
+
+function _quarantineGeneratedFeedback(db) {
+  const rows = db.prepare(`
+    SELECT id, source_type, source_path, source_ref, status, body, metadata
+    FROM memory_records
+    WHERE status='active' AND source_type='knowledge-base'
+  `).all();
+  const update = db.prepare(`
+    UPDATE memory_records
+    SET status='candidate', metadata=?, updated_at=?
+    WHERE id=? AND status='active'
+  `);
+  const now = Date.now();
+  for (const row of rows) {
+    const provenance = _generatedFeedbackProvenance(row);
+    if (!provenance) continue;
+    update.run(JSON.stringify({
+      ...provenance.metadata,
+      legacyUnverified: true,
+      candidateState: 'legacy-unverified',
+      legacySourceType: row.source_type,
+      legacySourceRef: provenance.sourceRef,
+      quarantinedBy: 'migration-027',
+    }), now, row.id);
+  }
+}
+
+module.exports = {
+  version: 27,
+  description: 'review-learning candidates, retrieval traces, and lifecycle events',
+  up(db) {
+    _addColumn(db, 'memory_retrieval_runs', 'dispatch_id TEXT');
+    _addColumn(db, 'memory_retrieval_runs', "retrieval_kind TEXT NOT NULL DEFAULT 'general'");
+    _addColumn(db, 'memory_retrieval_runs', "selected_ids TEXT NOT NULL DEFAULT '[]'");
+    _addColumn(db, 'memory_retrieval_runs', "decision_trace TEXT NOT NULL DEFAULT '[]'");
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_memory_retrieval_dispatch_kind
+        ON memory_retrieval_runs(dispatch_id, retrieval_kind, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS memory_lifecycle_events (
+        id            INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_key     TEXT NOT NULL UNIQUE CHECK(length(event_key) <= 64),
+        event_type    TEXT NOT NULL CHECK(length(event_type) <= 64),
+        memory_id     TEXT,
+        finding_key   TEXT,
+        project       TEXT NOT NULL CHECK(length(project) <= 120),
+        agent         TEXT,
+        area          TEXT NOT NULL DEFAULT 'general' CHECK(length(area) <= 360),
+        disposition   TEXT,
+        work_item_id  TEXT,
+        dispatch_id   TEXT,
+        metadata      TEXT NOT NULL DEFAULT '{}' CHECK(length(metadata) <= 8192),
+        created_at    INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_memory_lifecycle_project_area_created
+        ON memory_lifecycle_events(project, area, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lifecycle_finding
+        ON memory_lifecycle_events(finding_key, event_type, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lifecycle_memory
+        ON memory_lifecycle_events(memory_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lifecycle_dispatch
+        ON memory_lifecycle_events(dispatch_id, created_at DESC);
+
+      CREATE INDEX IF NOT EXISTS idx_memory_review_learning_active
+        ON memory_records(scope_key, updated_at DESC)
+        WHERE source_type='review-learning'
+          AND memory_type='procedural'
+          AND scope_type='project'
+          AND status='active';
+    `);
+
+    _quarantineGeneratedFeedback(db);
+  },
+};

package/engine/dispatch.js

@@ -977,6 +977,35 @@ function markCompletedSourceWorkItem(item) {
 
 // ─── Complete Dispatch ───────────────────────────────────────────────────────
 
+const WORKTREE_PROTECTION_RETRY_MS = 60 * 1000;
+
+function deferDispatchForWorktreeProtection(id, protection = {}, terminal = {}) {
+  let deferred = false;
+  const now = Date.now();
+  mutateDispatch((dispatch) => {
+    const item = (dispatch.active || []).find(entry => entry.id === id);
+    if (!item) return dispatch;
+    const previous = item._worktreeProtectionDeferred || {};
+    const previousTerminal = previous.terminal || {};
+    item._worktreeProtectionDeferred = {
+      deferredAt: previous.deferredAt || new Date(now).toISOString(),
+      retryAfter: new Date(now + WORKTREE_PROTECTION_RETRY_MS).toISOString(),
+      protectionReason: protection.reason || previous.protectionReason || 'preservation-failed',
+      ...(protection.error ? { error: String(protection.error) } : {}),
+      terminal: {
+        reason: terminal.reason || previousTerminal.reason || '',
+        resultSummary: terminal.resultSummary || previousTerminal.resultSummary || '',
+        completeOpts: terminal.completeOpts && typeof terminal.completeOpts === 'object'
+          ? terminal.completeOpts
+          : (previousTerminal.completeOpts || {}),
+      },
+    };
+    deferred = true;
+    return dispatch;
+  });
+  return deferred;
+}
+
 function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', resultSummary = '', opts = {}) {
   const {
     processWorkItemFailure = true,
@@ -1033,6 +1062,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     delete item.prompt;
     delete item._promptFile;
     delete item._promptBytes;
+    delete item._worktreeProtectionDeferred;
     if (dispatch.completed.length >= 100) {
       dispatch.completed = dispatch.completed.slice(-100);
     }
@@ -1208,6 +1238,8 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
           // Human-readable labels for each failure class — used as fallback when reason is empty
           const CLASS_LABELS = {
             [FAILURE_CLASS.EMPTY_OUTPUT]: 'agent produced no output \u2014 likely crashed on startup',
+            [FAILURE_CLASS.RUNTIME_TRUNCATED_EXIT]: 'runtime process ended mid-turn (exit 0 with an unfinished tool call) \u2014 no terminal result and no completion report; retry re-runs the truncated turn',
+            [FAILURE_CLASS.RUNTIME_SESSION_STALE]: 'resumed runtime session was unusable (conversation purged, or its working directory no longer exists) \u2014 cached session cleared so the retry starts fresh',
             [FAILURE_CLASS.BUILD_FAILURE]: 'build/test/lint failure in output',
             [FAILURE_CLASS.MERGE_CONFLICT]: 'merge conflict',
             [FAILURE_CLASS.DEPENDENCY_MERGE_SETUP]: 'dependency merge setup failed',
@@ -1525,6 +1557,7 @@ module.exports = {
   addToDispatchWithValidation,
   getPrDispatchDedupeKey,
   isRetryableFailureReason,
+  deferDispatchForWorktreeProtection,
   completeDispatch,
   writeInboxAlert,
   updateAgentStatus,

package/engine/distribution.js

@@ -0,0 +1,189 @@
+// engine/distribution.js — identity of the *installed* Minions distribution.
+//
+// Minions ships from one source tree as two npm packages (tools/prepare-package.js):
+//   • public   → `@yemi33/minions`               (npmjs, yemi33/minions)
+//   • internal → `@yemishin_microsoft/minions`   (GitHub Packages; overridable
+//                                                 at publish time via INTERNAL_PACKAGE_NAME)
+//
+// Distribution identity is derived ONLY from the installed package manifest —
+// the `name` field npm resolved this runtime from. Repository remotes, branch
+// names, checkout paths and config values are all operator-mutable and are
+// deliberately NOT consulted: a public install must never be mistaken for an
+// internal one because someone added an opg remote.
+//
+// Also owns the *installation identity* (`installationId`) that internal-only
+// first-run surfaces key their acknowledgement on. It lives in the SQL
+// small-state `engine_state` blob, so it survives dashboard/engine restarts and
+// package upgrades, while a genuinely new runtime installation (fresh
+// engine/state.db) gets a fresh id. The internal install/state-migration path
+// consumes the same helpers so both agree on what "this installation" means.
+
+const fs = require('fs');
+const path = require('path');
+
+const PUBLIC_PACKAGE_NAME = '@yemi33/minions';
+
+const DISTRIBUTION_CHANNEL = {
+  PUBLIC: 'public',
+  INTERNAL: 'internal',
+};
+
+// Exact copy required by W-ms1jgr95000ke749 — the popup's primary message.
+const INTERNAL_WELCOME_MESSAGE = 'Welcome to the internal Minions!';
+
+const INSTALLATION_ID_KEY = 'installationId';
+const INTERNAL_WELCOME_ACK_KEY = 'internalWelcome';
+
+// The installed package root: engine/ lives one level under it in both the npm
+// tarball and the git checkout.
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+function _packageJsonPath(opts) {
+  if (opts && opts.packageJsonPath) return opts.packageJsonPath;
+  return path.join((opts && opts.packageRoot) || PACKAGE_ROOT, 'package.json');
+}
+
+// Read `{ name, version }` off the installed manifest. Returns null when the
+// manifest is missing or unparseable — callers treat that as "not internal".
+function readRuntimePackageMeta(opts) {
+  try {
+    const raw = fs.readFileSync(_packageJsonPath(opts), 'utf8');
+    const pkg = JSON.parse(raw);
+    if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg)) return null;
+    const name = typeof pkg.name === 'string' ? pkg.name.trim() : '';
+    const version = typeof pkg.version === 'string' ? pkg.version.trim() : '';
+    if (!name) return null;
+    return { name, version: version || null };
+  } catch {
+    return null;
+  }
+}
+
+// A Minions package is `minions` or `@scope/minions`. Anything else (a vendored
+// fork under a different product name, a corrupt manifest) is not classified as
+// an internal distribution — the internal-only surfaces stay hidden.
+function isMinionsPackageName(name) {
+  return typeof name === 'string' && /^(?:@[^/\s]+\/)?minions$/.test(name.trim());
+}
+
+// Internal == a recognised Minions package that is NOT the public one.
+// Fail closed: unknown / unreadable / non-Minions names are never internal.
+function isInternalPackageName(name) {
+  if (!isMinionsPackageName(name)) return false;
+  return name.trim() !== PUBLIC_PACKAGE_NAME;
+}
+
+// { packageName, version, channel, isInternal }. `packageName` is null when the
+// manifest could not be read.
+function resolveDistribution(opts) {
+  const meta = readRuntimePackageMeta(opts);
+  const packageName = meta ? meta.name : null;
+  const isInternal = isInternalPackageName(packageName);
+  return {
+    packageName,
+    version: meta ? meta.version : null,
+    channel: isInternal ? DISTRIBUTION_CHANNEL.INTERNAL : DISTRIBUTION_CHANNEL.PUBLIC,
+    isInternal,
+  };
+}
+
+function _smallState() {
+  return require('./small-state-store');
+}
+
+function _newInstallationId() {
+  return require('crypto').randomUUID();
+}
+
+// Stable per-installation id, created on first read and persisted in SQL.
+// Deliberately NOT derived from a path or hostname: copying ~/.minions to a new
+// machine is the same installation, and two installations on one machine must
+// not collide.
+function resolveInstallationId() {
+  const store = _smallState();
+  const existing = store.readEngineState()[INSTALLATION_ID_KEY];
+  if (typeof existing === 'string' && existing) return existing;
+  const generated = _newInstallationId();
+  const { result } = store.applyEngineStateMutation((state) => {
+    if (typeof state[INSTALLATION_ID_KEY] === 'string' && state[INSTALLATION_ID_KEY]) return state;
+    state[INSTALLATION_ID_KEY] = generated;
+    return state;
+  });
+  return result[INSTALLATION_ID_KEY] || generated;
+}
+
+// { ackedAt, installationId, packageName } | null
+function readInternalWelcomeAck() {
+  const ack = _smallState().readEngineState()[INTERNAL_WELCOME_ACK_KEY];
+  if (!ack || typeof ack !== 'object' || Array.isArray(ack)) return null;
+  if (typeof ack.ackedAt !== 'string' || !ack.ackedAt) return null;
+  return ack;
+}
+
+// Record the acknowledgement against the CURRENT installation id, so a package
+// upgrade (same state.db) stays acknowledged while a fresh installation does not
+// inherit it. Idempotent: re-acking keeps the original timestamp.
+function acknowledgeInternalWelcome(opts) {
+  const installationId = resolveInstallationId();
+  const distribution = resolveDistribution(opts);
+  const store = _smallState();
+  const { result } = store.applyEngineStateMutation((state) => {
+    const prev = state[INTERNAL_WELCOME_ACK_KEY];
+    const alreadyAcked = prev && typeof prev === 'object' && !Array.isArray(prev)
+      && typeof prev.ackedAt === 'string' && prev.ackedAt
+      && prev.installationId === installationId;
+    if (alreadyAcked) return state;
+    state[INTERNAL_WELCOME_ACK_KEY] = {
+      ackedAt: new Date().toISOString(),
+      installationId,
+      packageName: distribution.packageName,
+    };
+    return state;
+  });
+  return result[INTERNAL_WELCOME_ACK_KEY];
+}
+
+// The full payload the dashboard serves from GET /api/welcome.
+//
+// `show` is true only for an internal distribution whose acknowledgement is
+// missing or belongs to a different installation. SQL being unavailable resolves
+// to `show: false` rather than throwing — a broken state DB must not turn into a
+// popup on every refresh.
+function resolveInternalWelcomeState(opts) {
+  const distribution = resolveDistribution(opts);
+  const payload = {
+    show: false,
+    message: INTERNAL_WELCOME_MESSAGE,
+    distribution,
+    installationId: null,
+    ackedAt: null,
+  };
+  if (!distribution.isInternal) return payload;
+  try {
+    const installationId = resolveInstallationId();
+    const ack = readInternalWelcomeAck();
+    payload.installationId = installationId;
+    payload.ackedAt = ack && ack.installationId === installationId ? ack.ackedAt : null;
+    payload.show = !payload.ackedAt;
+  } catch {
+    payload.show = false;
+  }
+  return payload;
+}
+
+module.exports = {
+  PUBLIC_PACKAGE_NAME,
+  DISTRIBUTION_CHANNEL,
+  INTERNAL_WELCOME_MESSAGE,
+  INSTALLATION_ID_KEY,
+  INTERNAL_WELCOME_ACK_KEY,
+  PACKAGE_ROOT,
+  readRuntimePackageMeta,
+  isMinionsPackageName,
+  isInternalPackageName,
+  resolveDistribution,
+  resolveInstallationId,
+  readInternalWelcomeAck,
+  acknowledgeInternalWelcome,
+  resolveInternalWelcomeState,
+};

package/engine/execution-model.js

@@ -59,10 +59,69 @@ function resolveCommentExecutionModel({
   });
 }
 
+/**
+ * Honest, stable label for "no concrete model id is known — the runtime picked
+ * its own default". Never invent a model name and never render blank.
+ */
+function runtimeDefaultModelLabel(runtime) {
+  const name = typeof runtime === 'string' ? runtime.trim() : '';
+  return name ? `${name} default` : UNKNOWN_MODEL;
+}
+
+/**
+ * A model id we can show verbatim. `auto` is a request for the runtime to pick,
+ * not a concrete model — mirrors buildRuntimeModelEvidence's treatment in
+ * engine/queries.js.
+ */
+function concreteExecutionModel(value) {
+  const model = normalizeExecutionModel(value);
+  if (!model) return null;
+  return model.toLowerCase() === 'auto' ? null : model;
+}
+
+/**
+ * W-ms0ytfdd000d5a26 — Resolve the effective model for a work item.
+ *
+ * Persisted dispatch evidence always wins so later config edits cannot rewrite
+ * history:
+ *   1. `dispatchEntry.executionModel` — what the runtime reported it ran.
+ *   2. `dispatchEntry.requestedModel` — what Minions sent via `--model`.
+ *   3. `<runtime> default`            — it ran, but nothing concrete was pinned
+ *                                       or reported.
+ * Only a work item with no dispatch record at all falls through to the caller's
+ * current-config resolution (`configuredRuntime` / `configuredModel`), which is
+ * flagged with `persisted: false` so the UI can say so.
+ *
+ * Runtime-agnostic by construction: the runtime is data carried on the record
+ * (or supplied by the caller), never branched on by name.
+ */
+function resolveWorkItemModel({ dispatchEntry, configuredRuntime, configuredModel } = {}) {
+  const fallbackRuntime = typeof configuredRuntime === 'string' ? configuredRuntime.trim() : '';
+  const build = (model, source, runtime, persisted) => ({
+    model: model || null,
+    label: model || runtimeDefaultModelLabel(runtime),
+    source: model ? source : (runtime ? 'runtime-default' : 'unknown'),
+    runtime: runtime || null,
+    persisted,
+  });
+
+  if (dispatchEntry) {
+    const entryRuntime = typeof dispatchEntry.runtimeName === 'string' ? dispatchEntry.runtimeName.trim() : '';
+    const runtime = entryRuntime || fallbackRuntime;
+    const reported = concreteExecutionModel(dispatchEntry.executionModel);
+    if (reported) return build(reported, 'runtime-reported', runtime, true);
+    return build(concreteExecutionModel(dispatchEntry.requestedModel), 'requested', runtime, true);
+  }
+  return build(concreteExecutionModel(configuredModel), 'configured', fallbackRuntime, false);
+}
+
 module.exports = {
   UNKNOWN_MODEL,
   MODEL_ID_RE,
   normalizeExecutionModel,
+  concreteExecutionModel,
   resolveExecutionModel,
   resolveCommentExecutionModel,
+  runtimeDefaultModelLabel,
+  resolveWorkItemModel,
 };

package/engine/features.js

@@ -102,6 +102,18 @@ const FEATURES = {
     addedIn: '0.1.2233',
     expires: '2027-01-31',
   },
+  'review-learning-capture': {
+    description: 'Capture verified code-review findings as bounded, project-scoped review-learning candidates and procedural lessons.',
+    default: false,
+    addedIn: '0.1.2203',
+    expires: '2027-01-31',
+  },
+  'review-learning-recall': {
+    description: 'Recall bounded applicable review lessons through the dedicated project-scoped review-learning path.',
+    default: false,
+    addedIn: '0.1.2203',
+    expires: '2027-01-31',
+  },
 };
 
 const ENV_TRUTHY = new Set(['1', 'true', 'on', 'yes']);