atris 3.33.3 → 3.35.0

package/lib/task-db.js

@@ -27,6 +27,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 const { DatabaseSync } = require('node:sqlite');
+const reviewIntegrity = require('./review-integrity');
 
 const DEFAULT_DB_PATH = path.join(os.homedir(), '.atris', 'tasks.db');
 const TASK_EPISODES_FILE = path.join('.atris', 'state', 'task_episodes.jsonl');
@@ -108,7 +109,10 @@ function appendTaskCompletionLogs(db, row, { status, actor, action, proof } = {}
   const metadata = row.metadata && typeof row.metadata === 'object' ? row.metadata : {};
   const proofText = compactLogText(proof || metadata.latest_agent_proof || metadata.verify || '', 500);
   const member = existingMemberSlug(row.workspace_root, row, actor);
-  const title = status === 'failed' ? 'Task failed' : action === 'accepted' ? 'Task accepted' : 'Task completed';
+  const title = status === 'archived' ? 'Task archived'
+    : status === 'failed' ? 'Task failed'
+    : action === 'accepted' ? 'Task accepted'
+    : 'Task completed';
   const fields = {
     task: ref,
     title: row.title,
@@ -413,7 +417,7 @@ function listTasks(db, { workspaceRoot: ws, status, claimedBy, limit }) {
     FROM tasks
     ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
     ORDER BY
-      CASE status WHEN 'open' THEN 0 WHEN 'claimed' THEN 1 WHEN 'review' THEN 2 WHEN 'failed' THEN 3 WHEN 'done' THEN 4 ELSE 5 END,
+      CASE status WHEN 'open' THEN 0 WHEN 'claimed' THEN 1 WHEN 'review' THEN 2 WHEN 'failed' THEN 3 WHEN 'done' THEN 4 WHEN 'archived' THEN 5 ELSE 6 END,
       CASE WHEN tag='endgame' THEN 0 ELSE 1 END,
       created_at DESC
     ${limit ? 'LIMIT ' + Number(limit) : ''}
@@ -506,10 +510,13 @@ function releaseTask(db, { id, actor }) {
   return { released: true, row: updated, event };
 }
 
-function doneTask(db, { id, status, actor, allowReview = false, action, proof } = {}) {
+function doneTask(db, { id, status, actor, allowReview = false, action, proof, autoAccepted = false } = {}) {
   if (!id) throw new Error('id required');
   const final = status || 'done';
   if (!['done', 'failed'].includes(final)) throw new Error('status must be done|failed');
+  // 'archived' is a distinct terminal status written by archiveTask(), never
+  // by this function — a bulk sweep of duplicate/off-roadmap tasks must not
+  // read as a real failure. See archiveTask() below.
   const now = Date.now();
   const allowedStatuses = allowReview ? "'open', 'claimed', 'review'" : "'open', 'claimed'";
   const result = withBusyRetry(() => db.prepare(`
@@ -525,7 +532,11 @@ function doneTask(db, { id, status, actor, allowReview = false, action, proof }
       workspaceRoot: row.workspace_root,
       actor: actor || process.env.ATRIS_AGENT_ID || process.env.USER || null,
       eventType: final === 'done' ? 'completed' : 'blocked',
-      payload: { status: final, action: action || final },
+      payload: {
+        status: final,
+        action: action || final,
+        ...(autoAccepted ? { auto_accepted: true } : {}),
+      },
     });
     const logs = appendTaskCompletionLogs(db, row, {
       status: final,
@@ -538,11 +549,141 @@ function doneTask(db, { id, status, actor, allowReview = false, action, proof }
   return { updated: false };
 }
 
+// Distinct terminal status for housekeeping sweeps (duplicate loop-ticks,
+// off-roadmap backlog resets, synthetic-test cleanup). Never conflate this
+// with `failed` — 'failed' means the work itself did not succeed, 'archived'
+// means the work was swept off the board for reasons unrelated to whether it
+// succeeded. Reward/RSI signal readers must treat the two differently.
+// `fromFailed: true` is an explicit opt-in for sanctioned historical cleanup
+// (e.g. the 109 duplicate "Loop tick:" orphans fail-closed before 'archived'
+// existed — cluster 1 of failed-tasks-analysis-2026-07-03). It permits the
+// failed→archived transition and records the prior status in
+// metadata.archived_from. 'done' rows are never archivable: accepted work
+// stays done, with or without the flag.
+function archiveTask(db, { id, actor, reason, fromFailed = false } = {}) {
+  if (!id) throw new Error('id required');
+  const reasonText = String(reason || '').trim();
+  if (!reasonText) throw new Error('reason required');
+  const row = getTask(db, id);
+  if (!row) return { archived: false, reason: 'not_found' };
+  const allowedStatuses = fromFailed
+    ? ['open', 'claimed', 'review', 'failed']
+    : ['open', 'claimed', 'review'];
+  if (!allowedStatuses.includes(row.status)) {
+    return { archived: false, reason: `already_${row.status}` };
+  }
+  const now = Date.now();
+  const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+  metadata.archived_reason = reasonText;
+  metadata.archived_at = new Date(now).toISOString();
+  metadata.archived_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+  metadata.approval_status = 'archived';
+  if (row.status === 'failed') metadata.archived_from = 'failed';
+  const statusPlaceholders = allowedStatuses.map(() => '?').join(', ');
+  const result = withBusyRetry(() => db.prepare(`
+    UPDATE tasks
+       SET status = 'archived',
+           done_at = ?,
+           updated_at = ?,
+           metadata = ?
+     WHERE id = ?
+       AND status IN (${statusPlaceholders})
+  `).run(now, now, JSON.stringify(metadata), id, ...allowedStatuses));
+  if (result.changes !== 1) return { archived: false, reason: 'stale_task_state' };
+  const updated = getTask(db, id);
+  const event = appendTaskEvent(db, {
+    taskId: id,
+    workspaceRoot: updated.workspace_root,
+    actor: metadata.archived_by,
+    eventType: 'archived',
+    payload: { reason: reasonText, ...(row.status === 'failed' ? { previous_status: 'failed' } : {}) },
+  });
+  const logs = appendTaskCompletionLogs(db, updated, {
+    status: 'archived',
+    actor: metadata.archived_by,
+    action: 'archived',
+    proof: reasonText,
+  });
+  return { archived: true, event, row: updated, logs };
+}
+
+// Marks metadata written by the 2026-06-10 "first-principles backlog reset"
+// (see atris/logs/2026/2026-06-10.md) — a bulk pass that closed off-roadmap
+// tasks, including certified/proof-backed done work, by writing status
+// 'failed' because no distinct 'archived' status existed yet. This
+// identifies exactly those rows so relabelArchivedTasks() can fix the label
+// without touching any task that failed for a real reason.
+function isJune10BacklogResetMarker(metadata) {
+  const m = metadata && typeof metadata === 'object' ? metadata : {};
+  if (!m.archived_at) return false;
+  return /first-principles backlog reset 2026-06-10/i.test(String(m.archive_reason || ''));
+}
+
+// One-time migration (OBL-1622): relabel the June-10 mislabeled rows from
+// 'failed' to 'archived'. Dry-run only counts/samples; --apply performs the
+// same status write path as archiveTask() (direct projection UPDATE +
+// appendTaskEvent), never a raw projection-JSON edit.
+function relabelArchivedTasks(db, { workspaceRoot: ws, apply = false, actor, limit = 5000 } = {}) {
+  const candidates = listTasks(db, { workspaceRoot: ws || null, status: 'failed', limit })
+    .filter(row => isJune10BacklogResetMarker(row.metadata));
+  const sample = candidates.slice(0, 10).map(row => ({ id: row.id, title: row.title }));
+  if (!apply) {
+    return { applied: false, count: candidates.length, sample };
+  }
+  const now = Date.now();
+  const actorText = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+  const relabeledIds = [];
+  for (const row of candidates) {
+    const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+    metadata.relabeled_from_status = 'failed';
+    metadata.relabeled_at = new Date(now).toISOString();
+    metadata.relabeled_by = actorText;
+    metadata.relabel_reason = 'obl_1622_june_10_backlog_reset_relabel';
+    const result = withBusyRetry(() => db.prepare(`
+      UPDATE tasks
+         SET status = 'archived',
+             updated_at = ?,
+             metadata = ?
+       WHERE id = ?
+         AND status = 'failed'
+    `).run(now, JSON.stringify(metadata), row.id));
+    if (result.changes === 1) {
+      appendTaskEvent(db, {
+        taskId: row.id,
+        workspaceRoot: row.workspace_root,
+        actor: actorText,
+        eventType: 'relabeled_archived',
+        payload: { previous_status: 'failed', reason: 'obl_1622_june_10_backlog_reset_relabel' },
+      });
+      relabeledIds.push(row.id);
+    }
+  }
+  return { applied: true, count: relabeledIds.length, ids: relabeledIds, sample };
+}
+
 function cleanLandingText(value) {
   const text = String(value || '').replace(/\s+/g, ' ').trim();
   return text || null;
 }
 
+// Record who delivered this review pass and answer whether certification is
+// allowed: at least one recorded pass actor must differ from the builder.
+// The first pass actor stamps built_by; judge != worker from then on.
+function recordReviewPassActor(metadata, claimedBy, rawActor) {
+  const actorNorm = reviewIntegrity.normalizeActor(
+    rawActor || process.env.ATRIS_AGENT_ID || process.env.USER || ''
+  );
+  if (!metadata.built_by && actorNorm) metadata.built_by = actorNorm;
+  const actors = Array.isArray(metadata.agent_review_actors) ? [...metadata.agent_review_actors] : [];
+  if (actorNorm && !actors.includes(actorNorm)) actors.push(actorNorm);
+  metadata.agent_review_actors = actors;
+  const builder = reviewIntegrity.normalizeActor(metadata.built_by || claimedBy || '');
+  const independent = builder
+    ? (actors.find((a) => a && a !== builder) || null)
+    : (actors.length >= 2 ? actors[1] : null);
+  return { builder: builder || null, independent };
+}
+
 function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, resultTrace }) {
   if (!id) throw new Error('id required');
   const text = String(proof || '').trim();
@@ -567,11 +708,13 @@ function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, resul
     const cleaned = cleanLandingText(landingInput[key]);
     if (cleaned) metadata[`landing_${key}`] = cleaned;
   }
-  if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES) {
+  const passRecord = recordReviewPassActor(metadata, row.claimed_by, actor);
+  if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES && passRecord.independent) {
     metadata.agent_certified = true;
     metadata.agent_certified_at = new Date(now).toISOString();
     metadata.agent_certified_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
     metadata.agent_certification_policy = `${AGENT_CERTIFICATION_REVIEW_PASSES}_agent_review_passes`;
+    metadata.independent_review_by = passRecord.independent;
   }
   const result = withBusyRetry(() => db.prepare(`
     UPDATE tasks
@@ -1170,6 +1313,61 @@ function noteTask(db, { id, actor, content }) {
   return { noted: true, event };
 }
 
+function normalizeTagToken(value) {
+  return String(value == null ? '' : value).trim().toLowerCase();
+}
+
+// Update a task's flag list (`metadata.tags`) on an already-created task.
+// Tags are only settable at creation elsewhere; this is the after-the-fact
+// escape hatch so an open task that becomes an owner decision can be marked
+// `needs-human` — which sweep and fleet staffing both honor — instead of
+// being restaffed forever (CLI-879). Every change appends a
+// `task_tags_updated` event so the trail shows who flagged it and when.
+function tagTask(db, { id, actor, add = [], remove = [] } = {}) {
+  if (!id) throw new Error('id required');
+  const addTags = [...new Set((Array.isArray(add) ? add : [add]).map(normalizeTagToken).filter(Boolean))];
+  const removeSet = new Set((Array.isArray(remove) ? remove : [remove]).map(normalizeTagToken).filter(Boolean));
+  if (!addTags.length && !removeSet.size) return { tagged: false, reason: 'no_tags' };
+  const row = getTask(db, id);
+  if (!row) return { tagged: false, reason: 'not_found' };
+  const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+  const before = [...new Set((Array.isArray(metadata.tags) ? metadata.tags : []).map(normalizeTagToken).filter(Boolean))];
+  const removed = [];
+  const next = before.filter((tag) => {
+    if (removeSet.has(tag)) { removed.push(tag); return false; }
+    return true;
+  });
+  const added = [];
+  for (const tag of addTags) {
+    // An explicit --remove of the same token wins over --add.
+    if (removeSet.has(tag)) continue;
+    if (!next.includes(tag)) { next.push(tag); added.push(tag); }
+  }
+  if (!added.length && !removed.length) {
+    return { tagged: false, reason: 'no_changes', tags: before };
+  }
+  metadata.tags = next;
+  const actorText = cleanStageText(actor) || null;
+  const now = Math.max(Date.now(), Number(row.updated_at || 0) + 1);
+  const result = withBusyRetry(() => db.prepare(`
+    UPDATE tasks
+       SET metadata = ?,
+           updated_at = ?
+     WHERE id = ?
+       AND updated_at = ?
+  `).run(JSON.stringify(metadata), now, id, row.updated_at));
+  if (result.changes !== 1) return { tagged: false, reason: 'stale_task_state' };
+  const updated = getTask(db, id);
+  const event = appendTaskEvent(db, {
+    taskId: id,
+    workspaceRoot: updated.workspace_root,
+    actor: actorText,
+    eventType: 'task_tags_updated',
+    payload: { added, removed, tags: next, previous_tags: before },
+  });
+  return { tagged: true, event, row: updated, tags: next, added, removed };
+}
+
 function taskChatPacketFromPayload(payload) {
   const data = payload && typeof payload === 'object' ? payload : {};
   const lines = ['TASK_CHAT_UPDATE'];
@@ -1235,7 +1433,7 @@ function chatTask(db, { id, actor, content, goal, summary }) {
   };
 }
 
-function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, careerXpEligible = false, clearedFields = [], landing = {} }) {
+function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, careerXpEligible = false, clearedFields = [], landing = {}, autoAccepted = false }) {
   if (!id) throw new Error('id required');
   const row = getTask(db, id);
   if (!row) return { reviewed: false, reason: 'not_found' };
@@ -1243,6 +1441,14 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
   const now = Date.now();
   const reviewer = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
   const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+  const reviewerNorm = reviewIntegrity.normalizeActor(reviewer);
+  const builderNorm = reviewIntegrity.taskBuilder(row);
+  // judge != worker applies pre-acceptance only: a builder cannot positive-
+  // reward their own row while it still sits in review. Done rows are past
+  // the human gate; finish and post-acceptance XP bookkeeping stay open.
+  if (numericReward > 0 && row.status === 'review' && builderNorm && reviewerNorm && reviewerNorm === builderNorm) {
+    return { reviewed: false, reason: 'judge_equals_worker', builder: builderNorm };
+  }
   const proofText = String(proof || '').trim();
   const verifyText = cleanStageText(verify);
   const lessonText = String(lesson || '').trim();
@@ -1284,11 +1490,13 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
   if (reviewingPendingProof) {
     reviewPassCount += 1;
     metadata.agent_review_pass_count = reviewPassCount;
-    if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES) {
+    const passRecord = recordReviewPassActor(metadata, row.claimed_by, reviewer);
+    if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES && passRecord.independent) {
       metadata.agent_certified = true;
       metadata.agent_certified_at = new Date(now).toISOString();
       metadata.agent_certified_by = reviewer;
       metadata.agent_certification_policy = `${AGENT_CERTIFICATION_REVIEW_PASSES}_agent_review_passes`;
+      metadata.independent_review_by = passRecord.independent;
     }
   }
   if (numericReward > 0 && row.status === 'done') {
@@ -1312,6 +1520,7 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
     verify: verifyText || null,
     career_xp_eligible: Boolean(careerXpEligible),
   };
+  if (autoAccepted) payload.auto_accepted = true;
   if (reviewingPendingProof) {
     payload.review_pass_count = reviewPassCount;
     payload.agent_certified = metadata.agent_certified === true;
@@ -1762,11 +1971,15 @@ module.exports = {
   backlogTask,
   clearPlanTasks,
   doneTask,
+  archiveTask,
+  relabelArchivedTasks,
+  isJune10BacklogResetMarker,
   readyTask,
   reviseTask,
   stageTask,
   noteTask,
   chatTask,
+  tagTask,
   reviewTask,
   appendTaskEvent,
   listTaskEvents,

package/lib/task-proof.js

@@ -9,6 +9,8 @@ const RECEIPT_OR_ARTIFACT_RE = /\b(?:receipt|artifact|screenshot|log|trace|path=
 const RESULT_PAIR_RE = /\b(?:typecheck|build|smoke|test|pytest|verifier|validation|validated|verified|render|diff|sync|lineage|projection)\b.{0,80}\b(?:pass|passed|failed|green|ok|exit\s*0|reviewed)\b|\b(?:pass|passed|failed|green|ok|exit\s*0|reviewed)\b.{0,80}\b(?:typecheck|build|smoke|test|pytest|verifier|validation|validated|verified|render|diff|sync|lineage|projection)\b/i;
 const HUMAN_PROOF_RE = /\b(?:team human approved|human approved|human approval|approved by|accepted by|reviewed by|customer replied|customer approved|customer accepted|replied)\b/i;
 const FILE_ACTION_RE = /\b(?:changed|updated|edited|created|deleted|saved|wrote|patched|reviewed|verified|validated|opened|read)\b/i;
+const VERIFIED_PROOF_RE = /^\[verified\]\s+`[^`]+`\s+passed\s+\(exit 0\)(?:\s|$)/i;
+const SECOND_ACTOR_EXECUTED_PROOF_RE = /^Second-actor check:\s+`[^`]+`\s+re-run by [^,]+,\s+exited 0(?:[.\s]|$)/i;
 
 function compactWhitespace(text) {
   return String(text || '').replace(/\s+/g, ' ').trim();
@@ -37,6 +39,22 @@ function taskProofLooksMeaningful(proof) {
   return taskProofState(proof).ok;
 }
 
+function taskProofExecutionState(proof) {
+  const text = compactWhitespace(proof);
+  if (!text) return { ok: false, reason: 'proof_not_executed', detail: 'executed proof required' };
+  if (VERIFIED_PROOF_RE.test(text)) return { ok: true, reason: 'verified_proof' };
+  if (SECOND_ACTOR_EXECUTED_PROOF_RE.test(text)) return { ok: true, reason: 'second_actor_executed_proof' };
+  return {
+    ok: false,
+    reason: 'proof_not_executed',
+    detail: 'proof must come from an executed verifier, not a free-text claim that tests passed',
+  };
+}
+
+function taskProofLooksExecuted(proof) {
+  return taskProofExecutionState(proof).ok;
+}
+
 function tailText(text, max = 400) {
   const trimmed = String(text || '').trim();
   if (trimmed.length <= max) return trimmed;
@@ -73,6 +91,8 @@ function buildVerifiedProof(verifyCmd, baseProof = '', runner, options = {}) {
 
 module.exports = {
   taskProofLooksMeaningful,
+  taskProofLooksExecuted,
   taskProofState,
+  taskProofExecutionState,
   buildVerifiedProof,
 };

package/lib/task-receipt.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// Receipt writer for task proofs. Mirrors the mission receipt shape
+// (commands/mission.js writeReceipt) so lib/receipt-evidence.js can validate
+// paths named in a proof at the review gate: schema tag, `at` timestamp,
+// result.passed. Every call writes a receipt file, pass or fail — a failing
+// verifier still leaves a record, it just can't be cited to move a task to
+// ready.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function tailText(text, max = 400) {
+  const trimmed = String(text || '').trim();
+  if (trimmed.length <= max) return trimmed;
+  return `...${trimmed.slice(-max)}`;
+}
+
+function gitCommitHash(root) {
+  try {
+    const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' });
+    if (result.status === 0) return String(result.stdout || '').trim() || null;
+  } catch {
+    // ignore — not every workspace is a git repo
+  }
+  return null;
+}
+
+function runsDir(root) {
+  return path.join(root, 'atris', 'runs');
+}
+
+function slugifyTaskId(taskId) {
+  return String(taskId || 'task')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'task';
+}
+
+// Runs `command` for `taskId`, writes atris/runs/<date>-task-<id>-<time>.json,
+// and returns { ok, passed, receiptPath, exit, signal, output }. `ok` mirrors
+// `passed` — kept as a separate field so callers reading either name work.
+function writeTaskReceipt({ taskId, command, root = process.cwd(), runner } = {}) {
+  const cmd = String(command || '').trim();
+  if (!taskId) return { ok: false, passed: false, reason: 'task_id_required' };
+  if (!cmd) return { ok: false, passed: false, reason: 'verify_command_required' };
+  const run = runner || spawnSync;
+  const result = run('bash', ['-lc', cmd], {
+    cwd: root,
+    encoding: 'utf8',
+    timeout: 120000,
+  });
+  if (result.error) {
+    return { ok: false, passed: false, reason: 'verifier_spawn_failed', error: result.error.message, cmd };
+  }
+  const output = tailText(`${result.stdout || ''}${result.stderr || ''}`);
+  const passed = result.status === 0;
+  const dir = runsDir(root);
+  fs.mkdirSync(dir, { recursive: true });
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const safeTime = now.toISOString().replace(/[:.]/g, '-');
+  const receiptFile = path.join(dir, `${date}-task-${slugifyTaskId(taskId)}-${safeTime}.json`);
+  const receiptPath = path.relative(root, receiptFile);
+  const receipt = {
+    schema: 'atris.task_receipt.v1',
+    task_id: String(taskId),
+    command: cmd,
+    at: now.toISOString(),
+    commit: gitCommitHash(root),
+    result: {
+      passed,
+      exit: result.status,
+      signal: result.signal || null,
+      output,
+    },
+  };
+  fs.writeFileSync(receiptFile, JSON.stringify(receipt, null, 2) + '\n', 'utf8');
+  return {
+    ok: passed,
+    passed,
+    receiptPath,
+    receiptFile,
+    exit: result.status,
+    signal: result.signal || null,
+    output,
+    cmd,
+  };
+}
+
+module.exports = { writeTaskReceipt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.33.3",
+  "version": "3.35.0",
   "main": "bin/atris.js",
   "bin": {
     "atris": "bin/atris.js",

package/utils/update-check.js

@@ -5,6 +5,7 @@ const os = require('os');
 const { spawn, spawnSync } = require('child_process');
 
 const PACKAGE_NAME = 'atris';
+const NPM_SELF_UPDATE_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 const ATRIS_DIR = path.join(os.homedir(), '.atris');
 const CACHE_FILE = path.join(ATRIS_DIR, '.update-check');
@@ -217,13 +218,31 @@ async function checkForUpdates(force = false) {
   return null;
 }
 
-function showUpdateNotification(updateInfo) {
+function isGitCheckout(packageRoot = path.join(__dirname, '..')) {
+  return fs.existsSync(path.join(path.resolve(packageRoot), '.git'));
+}
+
+function getNpmSelfUpdateCommand() {
+  return NPM_SELF_UPDATE_COMMAND;
+}
+
+function getNpmSelfUpdateSpawnArgs() {
+  return {
+    command: 'npm',
+    args: ['install', '-g', `${PACKAGE_NAME}@latest`],
+  };
+}
+
+function showUpdateNotification(updateInfo, options = {}) {
   if (!updateInfo || !updateInfo.needsUpdate) return;
 
-  // Single yellow warning line — non-intrusive
+  const packageRoot = options.packageRoot || path.join(__dirname, '..');
   const yellow = '\x1b[33m';
   const reset = '\x1b[0m';
-  console.log(`${yellow}Update available: ${updateInfo.installed} → ${updateInfo.latest}. Run: atris upgrade${reset}`);
+  const installHint = isGitCheckout(packageRoot)
+    ? 'run: atris upgrade'
+    : `run: ${NPM_SELF_UPDATE_COMMAND}`;
+  console.log(`${yellow}update available: ${updateInfo.installed} -> ${updateInfo.latest}. ${installHint}${reset}`);
 }
 
 function inspectInstallGitState(packageRoot = path.join(__dirname, '..')) {
@@ -288,9 +307,8 @@ function shouldAutoUpdate(updateInfo, state, env = process.env) {
   if (mode === 'off') return false;
   if (mode === 'force') return true;
 
-  // Packaged npm installs are not git repositories. Git checkouts may be linked
-  // dev installs, where a global npm install would not update the code on PATH.
-  return !(state && state.isGitRepo);
+  const packageRoot = state && state.root ? state.root : path.join(__dirname, '..');
+  return !isGitCheckout(packageRoot);
 }
 
 function autoUpdate(updateInfo, options = {}) {
@@ -331,4 +349,7 @@ module.exports = {
   shouldAutoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
+  isGitCheckout,
+  getNpmSelfUpdateCommand,
+  getNpmSelfUpdateSpawnArgs,
 };

package/atris/learnings.jsonl

@@ -1 +0,0 @@
-{"ts":"2026-05-08T02:32:38.257Z","type":"pitfall","key":"narrow-grep-hides-matches","insight":"When operator says X exists in our code and a single-pattern grep returns 0 hits, do NOT conclude it does not exist. Run wider grep -rn first (whole backend/, not one subdir) before doubting. Tonight 2026-05-08: grepped \"gpt-5\\.5|gpt5\\.5|gpt-5p5\" in clients/ only, missed 20+ matches in routers/atris2_router.py + tests/, told operator gpt-5.5 was not wired. Operator was right.","confidence":5,"source":"observed","files":[]}