atris 3.15.13 → 3.15.22

package/commands/pull.js

@@ -7,7 +7,7 @@ const { loadConfig } = require('../utils/config');
 const { getLogPath } = require('../lib/file-ops');
 const { parseJournalSections, mergeSections, reconstructJournal } = require('../lib/journal');
 const { loadBusinesses, businessMatchesSlug } = require('./business');
-const { loadManifest, saveManifest, computeFileHash, buildManifest, computeLocalHashes, threeWayCompare } = require('../lib/manifest');
+const { loadManifest, saveManifest, computeFileHash, buildManifest, computeLocalHashes, threeWayCompare, isIgnoredSyncPath } = require('../lib/manifest');
 const { normalizeWikiOnlyPrefix } = require('../lib/wiki');
 const { emitSyncEvent, startTimer } = require('../lib/sync-telemetry');
 const { resolveSafeOutputDir } = require('../lib/workspace-safety');
@@ -37,6 +37,34 @@ function isBusinessWorkspaceRoot(dir) {
   return fs.existsSync(path.join(dir, '.atris', 'business.json')) && fs.existsSync(path.join(dir, 'atris'));
 }
 
+function normalizePullFilePath(filePath) {
+  if (!filePath) return null;
+  return `/${String(filePath).replace(/^\/+/, '')}`;
+}
+
+function mergeSmartPullFiles(hashFiles = [], batchFiles = [], changedPaths = []) {
+  const contentMap = {};
+  for (const f of batchFiles) {
+    const normalizedPath = normalizePullFilePath(f && f.path);
+    if (normalizedPath) contentMap[normalizedPath] = { ...f, path: normalizedPath };
+  }
+
+  const missingContent = changedPaths.filter((p) => {
+    const item = contentMap[p];
+    return !item || typeof item.content !== 'string';
+  });
+  if (missingContent.length > 0) {
+    return { ok: false, missingContent };
+  }
+
+  const files = hashFiles.map((f) => {
+    const normalizedPath = normalizePullFilePath(f && f.path);
+    const normalizedHashOnly = normalizedPath ? { ...f, path: normalizedPath } : f;
+    return contentMap[normalizedPath] || normalizedHashOnly;
+  });
+  return { ok: true, files };
+}
+
 function syncTimestamp() {
   return new Date().toISOString().replace(/[:.]/g, '-');
 }
@@ -75,7 +103,7 @@ function buildPullConflictReviewPacket(outputDir, conflictChanges, remoteContent
 async function pullAtris() {
   let arg = process.argv[3];
 
-  if (arg === '--help') {
+  if (arg === '--help' || arg === '-h' || arg === 'help') {
     console.log('Usage: atris pull [business] [--into <path>] [--only <prefix>] [--keep-local] [--timeout <seconds>] [--dry-run] [--no-manifest]');
     console.log('');
     console.log('  Pull is force-overwrite by default. Cloud is the source of truth.');
@@ -221,8 +249,8 @@ async function pullBusiness(slug) {
   // correct workspace for THIS business — i.e. it has a `.atris/business.json`
   // whose slug matches `slug`. Any other signal (a stray `atris/` folder, a
   // business.json for a different business, etc.) is NOT enough: pulling
-  // atris-labs-1 on top of a pallet workspace would mix two businesses into
-  // one directory and write pallet's manifest over atris-labs-1's (or vice
+  // atris-labs on top of another business workspace would mix two businesses into
+  // one directory and write one manifest over the other (or vice
   // versa), causing the next sync to do strange things.
   //
   // Fallback: create a fresh ./{slug}/ subdir. Always safe — even if cwd is
@@ -253,9 +281,9 @@ async function pullBusiness(slug) {
   // for a stray cwd to cause atris to delete user files.
   ({ dir: outputDir } = resolveSafeOutputDir(outputDir, { slug, op: 'pull into' }));
 
-  if (!onlyPrefixes && isBusinessWorkspaceRoot(outputDir)) {
-    onlyPrefixes = ['atris/'];
-  }
+  // Pull the whole business workspace by default. Older versions silently
+  // narrowed bound workspace pulls to atris/, which made staging snapshots and
+  // the real workspace diverge while both reported "synced".
 
   // Resolve business ID — always refresh from API to avoid stale workspace_id
   let businessId, workspaceId, businessName, resolvedSlug;
@@ -379,13 +407,16 @@ async function pullBusiness(slug) {
       // Diff against manifest to find changed files
       const remoteHashes = {};
       for (const f of hashResult.data.files) {
-        if (f.path && f.hash) remoteHashes[f.path] = f.hash;
+        const normalizedPath = normalizePullFilePath(f.path);
+        if (isIgnoredSyncPath(normalizedPath)) continue;
+        if (normalizedPath && f.hash) remoteHashes[normalizedPath] = f.hash;
       }
       const changedPaths = [];
       const manifestFiles = manifest.files || {};
       for (const [p, hash] of Object.entries(remoteHashes)) {
         const prev = manifestFiles[p];
-        if (!prev || prev.hash !== hash) changedPaths.push(p);
+        const missingLocally = !localFilesBeforePull[p];
+        if (!prev || prev.hash !== hash || missingLocally) changedPaths.push(p);
       }
 
       if (changedPaths.length === 0) {
@@ -419,17 +450,16 @@ async function pullBusiness(slug) {
 
         if (batchResult.ok && batchResult.data && batchResult.data.files) {
           process.stdout.write(`\r  Fetched ${batchResult.data.files.length} files in ${phase2Sec}s.${' '.repeat(10)}\n`);
-          // Merge: hash-only results + content for changed files
-          const contentMap = {};
-          for (const f of batchResult.data.files) {
-            if (f.path) contentMap[f.path] = f;
+          const merged = mergeSmartPullFiles(hashResult.data.files, batchResult.data.files, changedPaths);
+          if (merged.ok) {
+            result = { ok: true, data: { files: merged.files } };
+          } else {
+            process.stdout.write(`\r  Batch missing ${merged.missingContent.length} file(s), fetching full snapshot...${' '.repeat(10)}\n`);
+            const contentUrl = `/business/${businessId}/workspaces/${workspaceId}/snapshot?include_content=true${pathsParam}`;
+            result = await apiRequestJson(contentUrl, { method: 'GET', token: creds.token, timeoutMs });
+            const fullSec = Math.floor((Date.now() - startPhase2) / 1000);
+            process.stdout.write(`\r  Fetched in ${fullSec}s.${' '.repeat(20)}\n`);
           }
-          // Build merged file list: all hash-only entries + inject content for changed ones
-          const mergedFiles = hashResult.data.files.map(f => {
-            const withContent = contentMap[f.path];
-            return withContent || f;
-          });
-          result = { ok: true, data: { files: mergedFiles } };
         } else {
           // Batch not available — fall back to full snapshot
           process.stdout.write(`\r  Batch unavailable, fetching full snapshot...${' '.repeat(10)}\n`);
@@ -544,6 +574,9 @@ async function pullBusiness(slug) {
   const crypto = require('crypto');
   for (const file of files) {
     if (!file.path || file.binary) continue;
+    const normalizedPath = normalizePullFilePath(file.path);
+    if (!normalizedPath) continue;
+    if (isIgnoredSyncPath(normalizedPath)) continue;
     // An empty string IS valid content (a real, zero-byte file). The earlier
     // version excluded `content === ''` from the hasContent path, which made
     // empty files masquerade as hash-only entries; they'd then be recorded in
@@ -555,11 +588,11 @@ async function pullBusiness(slug) {
     if (hasContent) {
       // Full content available — hash from raw bytes (matches computeLocalHashes)
       const rawBytes = Buffer.from(file.content, 'utf-8');
-      remoteFiles[file.path] = { hash: crypto.createHash('sha256').update(rawBytes).digest('hex'), size: rawBytes.length };
-      remoteContent[file.path] = file.content;
+      remoteFiles[normalizedPath] = { hash: crypto.createHash('sha256').update(rawBytes).digest('hex'), size: rawBytes.length };
+      remoteContent[normalizedPath] = file.content;
     } else if (file.hash) {
       // Hash-only entry from smart pull — trust the cloud-reported hash
-      remoteFiles[file.path] = { hash: file.hash, size: file.size || 0 };
+      remoteFiles[normalizedPath] = { hash: file.hash, size: file.size || 0 };
     }
   }
 
@@ -598,8 +631,12 @@ async function pullBusiness(slug) {
 
   if (dryRun) {
     console.log('');
-    for (const p of [...diff.toPull, ...diff.newRemote]) {
-      const label = diff.newRemote.includes(p) ? 'new on computer' : 'updated on computer';
+    for (const p of [...diff.toPull, ...diff.newRemote, ...diff.deletedLocal]) {
+      const label = diff.newRemote.includes(p)
+        ? 'new on computer'
+        : diff.deletedLocal.includes(p)
+          ? 'missing locally, restored from computer'
+          : 'updated on computer';
       const icon = diff.newRemote.includes(p) ? '+' : '\u2193';
       console.log(`  ${icon} ${p.replace(/^\//, '')}  ${label}  (dry run)`);
     }
@@ -611,7 +648,7 @@ async function pullBusiness(slug) {
     }
 
     const parts = [];
-    const pullCount = diff.toPull.length + diff.newRemote.length;
+    const pullCount = diff.toPull.length + diff.newRemote.length + diff.deletedLocal.length;
     if (pullCount > 0) parts.push(`${pullCount} would be pulled`);
     if (diff.deletedRemote.length > 0) parts.push(`${diff.deletedRemote.length} local file${diff.deletedRemote.length === 1 ? '' : 's'} would be removed`);
     if (diff.unchanged.length > 0) parts.push(`${diff.unchanged.length} unchanged`);
@@ -632,13 +669,17 @@ async function pullBusiness(slug) {
   console.log('');
 
   // Pull files that changed remotely (and we didn't change locally)
-  for (const p of [...diff.toPull, ...diff.newRemote]) {
+  for (const p of [...diff.toPull, ...diff.newRemote, ...diff.deletedLocal]) {
     const content = remoteContent[p];
     if (!content && content !== '') continue;
     const localPath = path.join(outputDir, p.replace(/^\//, ''));
     fs.mkdirSync(path.dirname(localPath), { recursive: true });
     fs.writeFileSync(localPath, content);
-    const label = diff.newRemote.includes(p) ? 'new on computer' : 'updated on computer';
+    const label = diff.newRemote.includes(p)
+      ? 'new on computer'
+      : diff.deletedLocal.includes(p)
+        ? 'missing locally, restored from computer'
+        : 'updated on computer';
     const icon = diff.newRemote.includes(p) ? '+' : '\u2193';
     console.log(`  ${icon} ${p.replace(/^\//, '')}  ${label}`);
     pulled++;
@@ -736,7 +777,9 @@ async function pullBusiness(slug) {
     // If there's no prior manifest (first pull), there's nothing to sweep —
     // threeWayCompare already handled newRemote/conflicts/newLocal, and we
     // have no basis for claiming ownership of any local-only file.
-    const managedPaths = manifest && manifest.files ? Object.keys(manifest.files) : [];
+    const managedPaths = manifest && manifest.files
+      ? Object.keys(manifest.files).filter((p) => !isIgnoredSyncPath(p))
+      : [];
     const sweepCandidates = managedPaths.filter(isInScope).filter((p) => localFiles[p]);
     const inScopeLocal = Object.keys(localFiles).filter(isInScope);
 
@@ -1059,4 +1102,4 @@ async function pullMemberJournal(token, agentId, memberName, memberDir) {
   return synced;
 }
 
-module.exports = { buildPullConflictReviewPacket, pullAtris };
+module.exports = { buildPullConflictReviewPacket, mergeSmartPullFiles, normalizePullFilePath, pullAtris };

package/commands/push.js

@@ -4,7 +4,7 @@ const crypto = require('crypto');
 const { loadCredentials } = require('../utils/auth');
 const { apiRequestJson } = require('../utils/api');
 const { loadBusinesses, saveBusinesses, businessMatchesSlug } = require('./business');
-const { loadManifest, saveManifest, buildManifest, computeLocalHashes } = require('../lib/manifest');
+const { loadManifest, saveManifest, buildManifest, computeLocalHashes, isIgnoredSyncPath, filterSyncFiles } = require('../lib/manifest');
 const { normalizeWikiOnlyPrefix } = require('../lib/wiki');
 const { emitSyncEvent, startTimer } = require('../lib/sync-telemetry');
 const { assertSafeWorkspaceRoot } = require('../lib/workspace-safety');
@@ -59,6 +59,7 @@ function buildPushChangePlan({
   baseFiles = {},
   onlyPrefixes = null,
   readFileContent,
+  isLocalFilePresent,
 } = {}) {
   const filesToPush = [];
   const deletedPaths = [];
@@ -79,7 +80,9 @@ function buildPushChangePlan({
   for (const filePath of Object.keys(baseFiles)) {
     if (!pathInScope(filePath, onlyPrefixes)) continue;
     if (basenameOfManifestPath(filePath).startsWith('.')) continue;
+    if (isIgnoredSyncPath(filePath)) continue;
     if (!localFiles[filePath]) {
+      if (isLocalFilePresent && isLocalFilePresent(filePath)) continue;
       deletedPaths.push(filePath);
     }
   }
@@ -104,11 +107,153 @@ function isMassDeletePlan({ deletedPaths = [], filesToPush = [], unchangedCount
   return deleteCount >= 10 && deleteCount > survivingCount;
 }
 
+function cleanManifestPath(filePath) {
+  const s = String(filePath || '').replace(/\\/g, '/');
+  return s.startsWith('/') ? s : `/${s}`;
+}
+
+function buildCloudHashMap(files = []) {
+  const cloudHashes = {};
+  for (const f of files) {
+    const normalizedPath = f && f.path ? cleanManifestPath(f.path) : null;
+    if (normalizedPath && f.hash) cloudHashes[normalizedPath] = f.hash;
+  }
+  return cloudHashes;
+}
+
+function isSyncReviewArtifactPath(filePath) {
+  const cleaned = cleanManifestPath(filePath);
+  return ['.remote', '.local', '.base', '.cloud'].some((suffix) => cleaned.endsWith(suffix));
+}
+
+function isNestedWorkspacePollutionPath(filePath, slug) {
+  const cleaned = cleanManifestPath(filePath);
+  const cleanSlug = String(slug || '').trim().replace(/^\/+|\/+$/g, '');
+  if (!cleanSlug) return false;
+  return cleaned === `/${cleanSlug}` || cleaned.startsWith(`/${cleanSlug}/`);
+}
+
+function analyzePushSafety({
+  filesToPush = [],
+  deletedPaths = [],
+  unchangedCount = 0,
+  onlyPrefixes = null,
+  slug = null,
+  allowBroadWorkspace = false,
+  allowNestedWorkspace = false,
+  allowSyncArtifacts = false,
+} = {}) {
+  const changedPaths = [
+    ...filesToPush.map((file) => cleanManifestPath(file.path)),
+    ...deletedPaths.map((filePath) => cleanManifestPath(filePath)),
+  ];
+  const changeCount = changedPaths.length;
+  const rootChanged = changedPaths.filter((filePath) => filePath.split('/').filter(Boolean).length === 1);
+  const topLevels = new Set(changedPaths.map((filePath) => filePath.split('/').filter(Boolean)[0]).filter(Boolean));
+  const nestedWorkspacePaths = changedPaths.filter((filePath) => isNestedWorkspacePollutionPath(filePath, slug));
+  const syncArtifactPaths = changedPaths.filter(isSyncReviewArtifactPath);
+  const reasons = [];
+
+  if (nestedWorkspacePaths.length > 0 && !allowNestedWorkspace) {
+    reasons.push(`nested workspace folder detected (${nestedWorkspacePaths.length} path${nestedWorkspacePaths.length === 1 ? '' : 's'})`);
+  }
+  if (syncArtifactPaths.length > 0 && !allowSyncArtifacts) {
+    reasons.push(`sync review artifacts detected (${syncArtifactPaths.length} path${syncArtifactPaths.length === 1 ? '' : 's'})`);
+  }
+  if (!onlyPrefixes && !allowBroadWorkspace) {
+    if (changeCount >= 25) {
+      reasons.push(`large unscoped workspace change (${changeCount} paths)`);
+    } else if (rootChanged.length >= 5) {
+      reasons.push(`many root files changed (${rootChanged.length} paths)`);
+    } else if (topLevels.size >= 8 && changeCount >= 10) {
+      reasons.push(`many top-level areas changed (${topLevels.size} areas)`);
+    }
+  }
+
+  return {
+    ok: reasons.length === 0,
+    reasons,
+    changedPaths,
+    changeCount,
+    unchangedCount,
+    rootChanged,
+    topLevelCount: topLevels.size,
+    nestedWorkspacePaths,
+    syncArtifactPaths,
+  };
+}
+
+function renderPushSafetyBlock(report, slug) {
+  const lines = [];
+  lines.push('');
+  lines.push('  Quest gate: review before publish');
+  lines.push('  ✗ Refusing unsafe workspace push.');
+  lines.push('');
+  lines.push(`    Planned change: ${report.changeCount} path${report.changeCount === 1 ? '' : 's'}, ${report.unchangedCount} unchanged.`);
+  for (const reason of report.reasons) {
+    lines.push(`    Reason: ${reason}.`);
+  }
+  const examples = [
+    ...report.nestedWorkspacePaths,
+    ...report.syncArtifactPaths,
+    ...report.changedPaths,
+  ];
+  const uniqueExamples = [...new Set(examples)].slice(0, 8);
+  if (uniqueExamples.length > 0) {
+    lines.push('');
+    lines.push('    First paths to review:');
+    uniqueExamples.forEach((filePath) => lines.push(`      - ${filePath.replace(/^\//, '')}`));
+  }
+  lines.push('');
+  lines.push('    Safe moves:');
+  lines.push(`      atris push ${slug || ''} --dry-run --only atris/now.md`.trimEnd());
+  lines.push('      atris sync --review');
+  lines.push('');
+  lines.push('    If this broad publish is intentional, rerun with:');
+  lines.push('      --allow-broad-workspace');
+  if (report.nestedWorkspacePaths.length > 0) lines.push('      --allow-nested-workspace');
+  if (report.syncArtifactPaths.length > 0) lines.push('      --allow-sync-artifacts');
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function parsePushTimeoutSec(argv = process.argv, defaultSec = 120) {
+  let raw = null;
+  const eqArg = argv.find(a => a.startsWith('--timeout='));
+  if (eqArg) raw = eqArg.slice('--timeout='.length);
+  else {
+    const idx = argv.indexOf('--timeout');
+    if (idx !== -1 && argv[idx + 1]) raw = argv[idx + 1];
+  }
+
+  const parsed = raw == null ? defaultSec : Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) return defaultSec;
+  return Math.max(5, Math.min(300, parsed));
+}
+
 async function pushAtris() {
   const elapsedMs = startTimer();
   let slug = process.argv[3];
   let _coldWake = false;
 
+  if (process.argv.includes('--help') || process.argv.includes('-h') || slug === 'help') {
+    console.log('Usage: atris push [business] [--from <path>] [--only <prefix>] [--force] [--delete] [--delete-all]');
+    console.log('');
+    console.log('  Push requires a fresh pull. If cloud has changed since your last pull,');
+    console.log('  the push will be blocked until you run `atris pull`. Use --force to override.');
+    console.log('');
+    console.log('  atris push                   Push from current folder (auto-detect business)');
+    console.log('  atris push example-co            Push example-co/ or atris/example-co/');
+    console.log('  atris push example-co --only team/nate   Only push files in team/nate/');
+    console.log('  atris push --force           Bypass freshness check (force-push, may overwrite cloud changes)');
+    console.log('  atris push --delete          Allow small cloud deletes shown by --dry-run');
+    console.log('  atris push --delete-all      Extra confirmation for mass-delete recovery');
+    console.log('  --allow-broad-workspace      Publish a large unscoped workspace plan after review');
+    console.log('  --allow-nested-workspace     Explicitly allow nested <slug>/ paths');
+    console.log('  --allow-sync-artifacts       Explicitly allow *.remote/*.local/*.base/*.cloud files');
+    process.exit(0);
+  }
+
   // Auto-detect business from .atris/business.json in current dir
   if (!slug || slug.startsWith('-')) {
     const bizFile = path.join(process.cwd(), '.atris', 'business.json');
@@ -128,11 +273,14 @@ async function pushAtris() {
     console.log('  the push will be blocked until you run `atris pull`. Use --force to override.');
     console.log('');
     console.log('  atris push                   Push from current folder (auto-detect business)');
-    console.log('  atris push pallet            Push pallet/ or atris/pallet/');
-    console.log('  atris push pallet --only team/nate   Only push files in team/nate/');
+    console.log('  atris push example-co            Push example-co/ or atris/example-co/');
+    console.log('  atris push example-co --only team/nate   Only push files in team/nate/');
     console.log('  atris push --force           Bypass freshness check (force-push, may overwrite cloud changes)');
     console.log('  atris push --delete          Allow small cloud deletes shown by --dry-run');
     console.log('  atris push --delete-all      Extra confirmation for mass-delete recovery');
+    console.log('  --allow-broad-workspace      Publish a large unscoped workspace plan after review');
+    console.log('  --allow-nested-workspace     Explicitly allow nested <slug>/ paths');
+    console.log('  --allow-sync-artifacts       Explicitly allow *.remote/*.local/*.base/*.cloud files');
     process.exit(0);
   }
 
@@ -140,7 +288,11 @@ async function pushAtris() {
   const dryRun = process.argv.includes('--dry-run');
   const allowDelete = process.argv.includes('--delete');
   const allowMassDelete = process.argv.includes('--delete-all');
+  const allowBroadWorkspace = process.argv.includes('--allow-broad-workspace');
+  const allowNestedWorkspace = process.argv.includes('--allow-nested-workspace');
+  const allowSyncArtifacts = process.argv.includes('--allow-sync-artifacts');
   const allowCrossRootManifest = process.argv.includes('--allow-cross-root-manifest');
+  const timeoutSec = parsePushTimeoutSec(process.argv);
 
   // Parse --only
   let onlyRaw = null;
@@ -167,7 +319,7 @@ async function pushAtris() {
   const sourceDir = resolvePushSourceDir({ slug });
   if (!sourceDir) {
     console.error(`No local folder found for "${slug}".`);
-    console.error('Run from inside a pulled folder, or: atris push pallet --from ./path');
+    console.error('Run from inside a pulled folder, or: atris push example-co --from ./path');
     process.exit(1);
   }
 
@@ -176,9 +328,8 @@ async function pushAtris() {
   // Refuse to walk/upload dangerous paths ($HOME, /, /Users, system dirs).
   assertSafeWorkspaceRoot(sourceDir, { slug, op: 'push from' });
 
-  if (!onlyPrefixes && isBusinessWorkspaceRoot(sourceDir)) {
-    onlyPrefixes = ['/atris/'];
-  }
+  // Push the whole business workspace by default. Brain-only sync must be
+  // explicit with --only atris/ so root workspace files cannot be missed.
 
   // Resolve business — always refresh from API
   let businessId, workspaceId, businessName, resolvedSlug;
@@ -280,11 +431,8 @@ async function pushAtris() {
       { method: 'GET', token: creds.token, timeoutMs: 60000 }
     );
     if (snapshotResult.ok && snapshotResult.data && Array.isArray(snapshotResult.data.files)) {
-      const cloudHashes = {};
-      for (const f of snapshotResult.data.files) {
-        if (f.path && f.hash) cloudHashes[f.path] = f.hash;
-      }
-      const manifestFiles = (manifest && manifest.files) || {};
+      const cloudHashes = filterSyncFiles(buildCloudHashMap(snapshotResult.data.files));
+      const manifestFiles = filterSyncFiles((manifest && manifest.files) || {});
       const driftFiles = [];
       // Direction 1: cloud has files the manifest doesn't know about, OR
       // cloud's hash differs from what we last pulled (someone changed it).
@@ -350,12 +498,13 @@ async function pushAtris() {
 
   // Compare local hashes to manifest — NO server call needed
   // Files where local hash differs from manifest = changed locally
-  const baseFiles = (manifest && manifest.files) ? manifest.files : {};
+  const baseFiles = filterSyncFiles((manifest && manifest.files) ? manifest.files : {});
   const { filesToPush, deletedPaths, unchangedCount } = buildPushChangePlan({
     localFiles,
     baseFiles,
     onlyPrefixes,
     readFileContent: (filePath) => fs.readFileSync(path.join(sourceDir, filePath.replace(/^\//, '')), 'utf8'),
+    isLocalFilePresent: (filePath) => fs.existsSync(path.join(sourceDir, filePath.replace(/^\//, ''))),
   });
 
   if (filesToPush.length === 0 && deletedPaths.length === 0) {
@@ -364,6 +513,23 @@ async function pushAtris() {
     return;
   }
 
+  const safetyReport = analyzePushSafety({
+    filesToPush,
+    deletedPaths,
+    unchangedCount,
+    onlyPrefixes,
+    slug: resolvedSlug || slug,
+    allowBroadWorkspace,
+    allowNestedWorkspace,
+    allowSyncArtifacts,
+  });
+
+  if (!safetyReport.ok && !dryRun) {
+    process.stdout.write(renderPushSafetyBlock(safetyReport, resolvedSlug || slug));
+    await emit('blocked', { error_detail: safetyReport.reasons.join('; ') });
+    process.exit(1);
+  }
+
   // Dry run — show what would be pushed without pushing
   if (dryRun) {
     console.log('');
@@ -383,6 +549,10 @@ async function pushAtris() {
       console.log('  Deletes require an explicit real push with --delete.');
       console.log('  If these deletes are unexpected, run `atris pull --keep-local` first.\n');
     }
+    if (!safetyReport.ok) {
+      process.stdout.write(renderPushSafetyBlock(safetyReport, resolvedSlug || slug));
+      console.log('  Dry run only: nothing was sent.\n');
+    }
     return;
   }
 
@@ -447,8 +617,14 @@ async function pushAtris() {
   };
   const wireFiles = (files) => files.map((f) => ({ path: toWirePath(f.path), content: f.content }));
   const syncFiles = (files) => apiRequestJson(
-    `/business/${businessId}/workspaces/${workspaceId}/sync`,
-    { method: 'POST', token: creds.token, body: { files: wireFiles(files) }, headers: { 'X-Atris-Actor-Source': 'cli' } }
+    `/business/${businessId}/workspaces/${workspaceId}/sync?timeout=${timeoutSec}`,
+    {
+      method: 'POST',
+      token: creds.token,
+      body: { files: wireFiles(files) },
+      headers: { 'X-Atris-Actor-Source': 'cli' },
+      timeoutMs: (timeoutSec + 15) * 1000,
+    }
   );
 
   // Inspect per-file results from a /sync response. Treat "written" and
@@ -596,7 +772,7 @@ async function pushAtris() {
   }
   if (deleteFailed.length > 0) {
     console.log('');
-    console.log(`  ⚠ ${deleteFailed.length} delete(s) failed (NOT marked as deleted in manifest):`);
+    console.log(`  ⚠ ${deleteFailed.length} ${deleteFailed.length === 1 ? 'delete' : 'deletes'} failed (NOT marked as deleted in manifest):`);
     deleteFailed.slice(0, 10).forEach((f) => console.log(`    ${f.status} ${f.path.replace(/^\//, '')}`));
     if (deleteFailed.length > 10) console.log(`    ... +${deleteFailed.length - 10} more`);
   }
@@ -625,7 +801,7 @@ async function pushAtris() {
   // These did NOT land on cloud even though the HTTP call returned 200.
   if (failedToLand.length > 0) {
     console.log('');
-    console.log(`  ⚠ ${failedToLand.length} file(s) did NOT land on cloud (server returned 200 but`);
+    console.log(`  ⚠ ${failedToLand.length} ${failedToLand.length === 1 ? 'file' : 'files'} did NOT land on cloud (server returned 200 but`);
     console.log(`     dropped or rejected these files):`);
     const shown = failedToLand.slice(0, 15);
     for (const f of shown) {
@@ -710,6 +886,12 @@ module.exports = {
   resolvePushSourceDir,
   canonicalWorkspaceRoot,
   basenameOfManifestPath,
+  buildCloudHashMap,
   isBusinessWorkspaceRoot,
   isMassDeletePlan,
+  parsePushTimeoutSec,
+  analyzePushSafety,
+  isNestedWorkspacePollutionPath,
+  isSyncReviewArtifactPath,
+  renderPushSafetyBlock,
 };

package/commands/review.js

@@ -29,9 +29,16 @@ function findReviewEngine() {
   return null;
 }
 
-function runReview(args) {
-  const enginePath = findReviewEngine();
-  if (!enginePath) {
+function printMissingReviewEngine(jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'Review engine not found.',
+      expected: 'atris/business/claude-code-review/workspace/review_engine.py',
+      specialists: ['Security', 'Testing', 'Performance', 'Maintainability', 'Database', 'Async'],
+      install: 'copy review_engine.py to your project',
+    }, null, 2));
+  } else {
     console.error('Review engine not found.');
     console.error('Expected at: atris/business/claude-code-review/workspace/review_engine.py');
     console.error('');
@@ -39,9 +46,20 @@ function runReview(args) {
     console.error('  Security, Testing, Performance, Maintainability, Database, Async');
     console.error('');
     console.error('Install: copy review_engine.py to your project');
-    process.exit(1);
   }
+  process.exit(1);
+}
+
+function exitReviewError(message, jsonMode, extra = {}) {
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: false, error: message, ...extra }, null, 2));
+  } else {
+    console.error(message);
+  }
+  process.exit(1);
+}
 
+function runReview(args) {
   // Parse args
   let file = null;
   let diffRef = null;
@@ -61,6 +79,11 @@ function runReview(args) {
     }
   }
 
+  const enginePath = findReviewEngine();
+  if (!enginePath) {
+    printMissingReviewEngine(jsonMode);
+  }
+
   // Build command
   const cmdArgs = ['python3', enginePath];
   if (file) {
@@ -74,11 +97,12 @@ function runReview(args) {
 
   if (allMode) {
     // Audit all Python services
-    console.log('Auditing all Python services...\n');
+    if (!jsonMode) console.log('Auditing all Python services...\n');
     const servicesDir = path.join(process.cwd(), 'backend', 'services');
     if (!fs.existsSync(servicesDir)) {
-      console.error('No backend/services/ directory found.');
-      process.exit(1);
+      exitReviewError('No backend/services/ directory found.', jsonMode, {
+        expected: 'backend/services/',
+      });
     }
 
     const files = fs.readdirSync(servicesDir).filter(f => f.endsWith('.py'));
@@ -107,6 +131,19 @@ function runReview(args) {
 
     issues.sort((a, b) => a.score - b.score);
 
+    if (jsonMode) {
+      console.log(JSON.stringify({
+        ok: true,
+        action: 'code_review_all',
+        services: files.length,
+        clean: cleanCount,
+        with_findings: issues.length,
+        total_findings: totalFindings,
+        issues,
+      }, null, 2));
+      return;
+    }
+
     console.log(`AUDIT: ${files.length} services | ${cleanCount} clean | ${issues.length} with findings\n`);
     if (issues.length > 0) {
       console.log(`${'Service'.padEnd(40)} ${'Score'.padStart(6)} ${'Findings'.padStart(8)}  Top Issue`);
@@ -131,15 +168,16 @@ function runReview(args) {
 
 async function reviewCommand(...args) {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log('Usage: atris review [file] [options]');
+    console.log('Usage: atris code-review [file] [options]   (alias: atris cr)');
     console.log('');
-    console.log('  atris review                   Review staged changes');
-    console.log('  atris review <file.py>         Review a specific file');
-    console.log('  atris review --diff HEAD~1     Review last commit');
-    console.log('  atris review --all             Audit all backend services');
-    console.log('  atris review --json            Machine-readable output');
+    console.log('  atris code-review                   Review staged changes');
+    console.log('  atris code-review <file.py>         Review a specific file');
+    console.log('  atris code-review --diff HEAD~1     Review last commit');
+    console.log('  atris code-review --all             Audit all backend services');
+    console.log('  atris code-review --json            Machine-readable output');
     console.log('');
     console.log('6 specialists: Security, Testing, Performance, Maintainability, Database, Async');
+    console.log('Note: this is distinct from `atris review` (the workflow validator step).');
     return;
   }