codemini-cli 0.6.2 → 0.6.4

package/src/core/command-policy.js

@@ -206,15 +206,66 @@ function allowedPathRoots(workspaceRoot, config = {}) {
     .map((item) => path.resolve(item));
 }
 
-function isWithinAnyRoot(candidatePath, roots = []) {
-  const resolvedCandidate = path.resolve(candidatePath);
-  return roots.some((root) => {
-    const relative = path.relative(root, resolvedCandidate);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-  });
-}
-
-function validateCdSegment(command, workspaceRoot, config = {}) {
+function isWithinAnyRoot(candidatePath, roots = []) {
+  const resolvedCandidate = path.resolve(candidatePath);
+  return roots.some((root) => {
+    const relative = path.relative(root, resolvedCandidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+  });
+}
+
+function normalizeWindowsPathForCompare(value) {
+  return String(value || '').trim().replace(/\//g, '\\').replace(/\\+$/g, '').toLowerCase();
+}
+
+function isWindowsPathWithinAnyRoot(candidatePath, roots = []) {
+  const candidate = normalizeWindowsPathForCompare(candidatePath);
+  if (!/^[a-z]:\\/i.test(candidate)) return false;
+  return roots.some((root) => {
+    const normalizedRoot = normalizeWindowsPathForCompare(root);
+    return candidate === normalizedRoot || candidate.startsWith(`${normalizedRoot}\\`);
+  });
+}
+
+function collectWindowsAbsolutePathCandidates(command) {
+  const text = String(command || '');
+  const candidates = [];
+  let current = '';
+  let quote = '';
+
+  const flush = () => {
+    const token = current.trim();
+    current = '';
+    if (/^[A-Za-z]:[\\/]/.test(token)) candidates.push(token);
+  };
+
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote) {
+        flush();
+        quote = '';
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === '\'') {
+      flush();
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      flush();
+      continue;
+    }
+    current += ch;
+  }
+  flush();
+  return candidates;
+}
+
+function validateCdSegment(command, workspaceRoot, config = {}) {
   const tokens = tokenizeTopLevel(command);
   if (tokens.length === 1) {
     return { allowed: false, reason: 'cd requires a target path in safe mode' };
@@ -279,20 +330,19 @@ export function evaluateCommandPolicy(command, config, workspaceRoot = process.c
     }
   }
 
-  const allowedLower = allowedPathRoots(workspaceRoot, config).map((item) => item.toLowerCase().replace(/\//g, '\\'));
-  const windowsAbsPath = lower.match(/[a-z]:\\[^\s'"]+/g) || [];
-  for (const p of windowsAbsPath) {
-    if (!allowedLower.some((root) => p === root || p.startsWith(`${root}\\`))) {
-      return { allowed: false, reason: `absolute path outside workspace or allowed paths: ${p}`, suggestion: suggestionForToken(token, config) };
-    }
-  }
-
-  const posixAbsPath = cmd.match(/(?<![:/\w])\/(?!\/)[^\s'"]+/g) || [];
-  const allowedResolved = allowedPathRoots(workspaceRoot, config);
-  for (const p of posixAbsPath) {
-    if (!isWithinAnyRoot(p, allowedResolved)) {
-      return { allowed: false, reason: `absolute path outside workspace or allowed paths: ${p}`, suggestion: suggestionForToken(token, config) };
-    }
+  const allowedRoots = allowedPathRoots(workspaceRoot, config);
+  const windowsAbsPath = collectWindowsAbsolutePathCandidates(cmd);
+  for (const p of windowsAbsPath) {
+    if (!isWindowsPathWithinAnyRoot(p, allowedRoots)) {
+      return { allowed: false, reason: `absolute path outside workspace or allowed paths: ${p}`, suggestion: suggestionForToken(token, config) };
+    }
+  }
+
+  const posixAbsPath = cmd.match(/(?<![:/\w])\/(?!\/)[^\s'"]+/g) || [];
+  for (const p of posixAbsPath) {
+    if (!isWithinAnyRoot(p, allowedRoots)) {
+      return { allowed: false, reason: `absolute path outside workspace or allowed paths: ${p}`, suggestion: suggestionForToken(token, config) };
+    }
   }
 
   return { allowed: true };

package/src/core/config-store.js

@@ -42,6 +42,7 @@ const DEFAULT_CONFIG = {
   },
   execution: {
     mode: 'normal',
+    approval_mode: 'review',
     always_allow_tools: [
       'read',
       'grep',
@@ -148,9 +149,16 @@ function normalizePolicyLists(config) {
   }
   next.model.name = String(next.model.name || DEFAULT_CONFIG.model.name).trim() || DEFAULT_CONFIG.model.name;
   next.model.fast_name = String(next.model.fast_name || '').trim();
-  next.execution.mode = ['auto', 'normal', 'plan'].includes(String(next.execution.mode || '').toLowerCase())
-    ? String(next.execution.mode).toLowerCase()
-    : 'normal';
+  const rawExecutionMode = String(next.execution.mode || '').toLowerCase();
+  const rawApprovalMode = String(next.execution.approval_mode || next.execution.approvalMode || '').toLowerCase().replace(/-/g, '_');
+  next.execution.mode = ['normal', 'plan'].includes(rawExecutionMode)
+    ? rawExecutionMode
+    : 'normal';
+  next.execution.approval_mode = ['review', 'auto', 'full_access'].includes(rawApprovalMode)
+    ? rawApprovalMode
+    : rawExecutionMode === 'auto'
+      ? 'auto'
+      : 'review';
   const rawTools = Array.isArray(next.execution.always_allow_tools)
     ? next.execution.always_allow_tools
     : [];

package/src/core/git-oplog-change-tracker.js

@@ -0,0 +1,387 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { normalizePath } from './string-utils.js';
+
+const CHANGE_OPLOG_VERSION = 1;
+const FILE_TOOLS = new Set(['edit', 'write', 'delete']);
+
+function runGit(args, { cwd, input = null, allowFailure = false, timeoutMs = 120_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, {
+      cwd,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch {}
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const stdoutBuffer = Buffer.concat(stdoutChunks);
+      const stderrBuffer = Buffer.concat(stderrChunks);
+      const result = {
+        code,
+        stdout: stdoutBuffer.toString('utf8'),
+        stderr: stderrBuffer.toString('utf8'),
+        stdoutBuffer,
+        stderrBuffer
+      };
+      if (code === 0 || allowFailure) resolve(result);
+      else reject(new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${code}`));
+    });
+    if (input != null) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+function changeId(prefix = 'op') {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${prefix}-${stamp}-${rand}`;
+}
+
+function normalizeRelativePath(value, { root = '' } = {}) {
+  let text = normalizePath(String(value || '').trim()).replace(/:\d+(?:-\d+)?$/, '');
+  if (!text || text === '.') return '';
+  if (/^[a-zA-Z]:\//.test(text) || text.startsWith('/')) {
+    if (!root) return '';
+    const absRoot = path.resolve(root);
+    const absTarget = path.resolve(text);
+    const rel = path.relative(absRoot, absTarget);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return '';
+    text = normalizePath(rel);
+  }
+  if (text.startsWith('../')) return '';
+  return text;
+}
+
+function extractPathCandidates(args = {}, declaredChanges = [], options = {}) {
+  const candidates = [];
+  for (const change of Array.isArray(declaredChanges) ? declaredChanges : [declaredChanges]) {
+    if (change?.path) candidates.push(change.path);
+  }
+  for (const value of [
+    args?.path,
+    args?.file,
+    args?.file_path,
+    args?.target,
+    args?.edit?.path,
+    args?.edit?.file,
+    args?.edit?.file_path,
+    args?.edit?.target?.path
+  ]) {
+    if (typeof value === 'string') candidates.push(value);
+  }
+  const out = [];
+  const seen = new Set();
+  for (const value of candidates) {
+    const normalized = normalizeRelativePath(value, options);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function parseStatusPaths(text) {
+  const parts = String(text || '').split('\0').filter(Boolean);
+  const paths = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const entry = parts[i];
+    if (entry.length < 4) continue;
+    const status = entry.slice(0, 2);
+    const filePath = normalizeRelativePath(entry.slice(3));
+    if (filePath) paths.push(filePath);
+    if (status.includes('R') || status.includes('C')) {
+      i += 1;
+      const renamedPath = normalizeRelativePath(parts[i] || '');
+      if (renamedPath) paths.push(renamedPath);
+    }
+  }
+  return [...new Set(paths)];
+}
+
+async function readWorktreeSnapshot(root, relativePath) {
+  const abs = path.resolve(root, relativePath);
+  if (!abs.startsWith(`${root}${path.sep}`) && abs !== root) {
+    return { exists: false, content: Buffer.alloc(0), hash: '' };
+  }
+  try {
+    const content = await fs.readFile(abs);
+    return { exists: true, content, hash: hashBuffer(content) };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, content: Buffer.alloc(0), hash: '' };
+    throw error;
+  }
+}
+
+async function readHeadSnapshot(root, relativePath) {
+  try {
+    const result = await runGit(['show', `HEAD:${relativePath}`], {
+      cwd: root,
+      allowFailure: true,
+      timeoutMs: 60_000
+    });
+    if (result.code !== 0) return { exists: false, content: Buffer.alloc(0), hash: '' };
+    return { exists: true, content: result.stdoutBuffer, hash: hashBuffer(result.stdoutBuffer) };
+  } catch {
+    return { exists: false, content: Buffer.alloc(0), hash: '' };
+  }
+}
+
+function hashBuffer(buffer) {
+  let hash = 5381;
+  for (const byte of buffer) hash = ((hash << 5) + hash + byte) >>> 0;
+  return hash.toString(16);
+}
+
+function countPatchLines(patch) {
+  let added = 0;
+  let removed = 0;
+  for (const line of String(patch || '').split(/\r?\n/)) {
+    if (line.startsWith('+++') || line.startsWith('---')) continue;
+    if (line.startsWith('+')) added += 1;
+    else if (line.startsWith('-')) removed += 1;
+  }
+  return { added, removed };
+}
+
+function firstChangedLineFromPatch(patch) {
+  const match = String(patch || '').match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/m);
+  return match ? Math.max(1, Number(match[1]) || 1) : 0;
+}
+
+function actionFromSnapshots(before, after) {
+  if (!before.exists && after.exists) return 'create';
+  if (before.exists && !after.exists) return 'delete';
+  return 'edit';
+}
+
+async function writeTempSnapshot(dir, name, snapshot) {
+  const filePath = path.join(dir, name);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, snapshot.content);
+  return filePath;
+}
+
+async function buildPatchForFile(root, relativePath, before, after) {
+  if (before.exists === after.exists && before.hash === after.hash) return '';
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'codemini-oplog-'));
+  try {
+    const oldPath = normalizePath(path.posix.join('old', relativePath));
+    const newPath = normalizePath(path.posix.join('new', relativePath));
+    const beforePath = await writeTempSnapshot(tmp, oldPath, before.exists ? before : { content: Buffer.alloc(0) });
+    const afterPath = await writeTempSnapshot(tmp, newPath, after.exists ? after : { content: Buffer.alloc(0) });
+    const result = await runGit([
+      'diff',
+      '--no-index',
+      '--no-color',
+      '--binary',
+      oldPath,
+      newPath
+    ], { cwd: tmp, allowFailure: true, timeoutMs: 120_000 });
+    if (result.code !== 1) return '';
+    const escaped = relativePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return result.stdout
+      .replace(new RegExp(`diff --git a/old/${escaped} b/new/${escaped}`), `diff --git a/${relativePath} b/${relativePath}`)
+      .replace(new RegExp(`--- a/old/${escaped}`), before.exists ? `--- a/${relativePath}` : '--- /dev/null')
+      .replace(new RegExp(`\\+\\+\\+ b/new/${escaped}`), after.exists ? `+++ b/${relativePath}` : '+++ /dev/null');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+export async function createGitOplogChangeTracker({ workspaceRoot = process.cwd(), sessionId } = {}) {
+  const startRoot = path.resolve(workspaceRoot);
+  const id = String(sessionId || '').trim();
+  if (!id) return { enabled: false, reason: 'missing-session' };
+
+  try {
+    const inside = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: startRoot, allowFailure: true });
+    if (inside.code !== 0 || inside.stdout.trim() !== 'true') {
+      return { enabled: false, reason: 'not-git-repo', workspaceRoot: startRoot };
+    }
+    const root = path.resolve((await runGit(['rev-parse', '--show-toplevel'], { cwd: startRoot })).stdout.trim());
+    const head = await runGit(['rev-parse', '--verify', 'HEAD'], { cwd: root, allowFailure: true });
+    const hasHead = head.code === 0;
+    const gitPath = (await runGit(['rev-parse', '--git-path', `codemini/sessions/${id}`], { cwd: root })).stdout.trim();
+    const oplogDir = path.resolve(root, gitPath);
+    const patchesDir = path.join(oplogDir, 'patches');
+    const opsDir = path.join(oplogDir, 'ops');
+    await fs.mkdir(patchesDir, { recursive: true });
+    await fs.mkdir(opsDir, { recursive: true });
+    if (hasHead) {
+      await runGit(['update-ref', `refs/codemini/sessions/${id}`, 'HEAD'], { cwd: root, allowFailure: true });
+    }
+    return {
+      enabled: true,
+      mode: 'git-oplog',
+      workspaceRoot: root,
+      sessionId: id,
+      baseCommit: hasHead ? head.stdout.trim() : '',
+      oplogDir,
+      patchesDir,
+      opsDir
+    };
+  } catch (error) {
+    return { enabled: false, reason: error instanceof Error ? error.message : String(error), workspaceRoot: startRoot };
+  }
+}
+
+export function isGitOplogChangeTrackerAvailable(tracker) {
+  return Boolean(tracker?.enabled && tracker.mode === 'git-oplog');
+}
+
+export async function beginGitOplogCapture(tracker, { toolName = '', args = {} } = {}) {
+  if (!isGitOplogChangeTrackerAvailable(tracker)) return null;
+  const explicitPaths = FILE_TOOLS.has(String(toolName || '')) ? extractPathCandidates(args, [], { root: tracker.workspaceRoot }) : [];
+  const status = await runGit(['status', '--porcelain=v1', '-z'], { cwd: tracker.workspaceRoot, allowFailure: true });
+  const dirtyPaths = parseStatusPaths(status.stdout);
+  const paths = explicitPaths.length ? explicitPaths : dirtyPaths;
+  const snapshots = new Map();
+  for (const filePath of paths) {
+    snapshots.set(filePath, await readWorktreeSnapshot(tracker.workspaceRoot, filePath));
+  }
+  return {
+    toolName,
+    explicit: explicitPaths.length > 0,
+    beforeDirtyPaths: dirtyPaths,
+    paths,
+    snapshots
+  };
+}
+
+export async function captureGitOplogChanges(tracker, capture, { toolName = '', toolCallId = '', summary = '', args = {}, declaredFileChanges = [] } = {}) {
+  if (!isGitOplogChangeTrackerAvailable(tracker) || !capture) return null;
+  const afterStatus = await runGit(['status', '--porcelain=v1', '-z'], { cwd: tracker.workspaceRoot, allowFailure: true });
+  const afterDirtyPaths = parseStatusPaths(afterStatus.stdout);
+  const declaredPaths = extractPathCandidates(args, declaredFileChanges, { root: tracker.workspaceRoot });
+  const candidates = new Set([
+    ...capture.paths,
+    ...declaredPaths,
+    ...(capture.explicit ? [] : capture.beforeDirtyPaths),
+    ...(capture.explicit ? [] : afterDirtyPaths)
+  ]);
+
+  const files = [];
+  const patches = [];
+  for (const filePath of candidates) {
+    const normalized = normalizeRelativePath(filePath, { root: tracker.workspaceRoot });
+    if (!normalized) continue;
+    let before = capture.snapshots.get(normalized);
+    if (!before) before = await readHeadSnapshot(tracker.workspaceRoot, normalized);
+    const after = await readWorktreeSnapshot(tracker.workspaceRoot, normalized);
+    const patch = await buildPatchForFile(tracker.workspaceRoot, normalized, before, after);
+    if (!patch.trim()) continue;
+    const stats = countPatchLines(patch);
+    files.push({
+      path: normalized,
+      action: actionFromSnapshots(before, after),
+      linesAdded: stats.added,
+      linesRemoved: stats.removed,
+      changedLine: firstChangedLineFromPatch(patch),
+      diffPreview: patch
+    });
+    patches.push(patch);
+  }
+  if (!files.length) return null;
+
+  const opId = changeId('op');
+  const patch = patches.join('\n');
+  const patchPath = path.join(tracker.patchesDir, `${opId}.patch`);
+  const opPath = path.join(tracker.opsDir, `${opId}.json`);
+  await fs.writeFile(patchPath, patch, 'utf8');
+  const op = {
+    version: CHANGE_OPLOG_VERSION,
+    id: opId,
+    sessionId: tracker.sessionId,
+    createdAt: new Date().toISOString(),
+    toolName,
+    toolCallId,
+    summary,
+    patchPath,
+    files: files.map(({ diffPreview, ...file }) => file),
+    revertedAt: null
+  };
+  await writeJson(opPath, op);
+  await fs.appendFile(path.join(tracker.oplogDir, 'ops.jsonl'), `${JSON.stringify({ ...op, patchPath: undefined })}\n`, 'utf8');
+  return files.map((file) => ({
+    ...file,
+    changeSetId: opId,
+    files: [{ path: file.path, action: file.action, linesAdded: file.linesAdded, linesRemoved: file.linesRemoved }]
+  }));
+}
+
+export async function listGitOplogChanges(tracker) {
+  if (!isGitOplogChangeTrackerAvailable(tracker)) return [];
+  let entries = [];
+  try {
+    entries = await fs.readdir(tracker.opsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    try { out.push(await readJson(path.join(tracker.opsDir, entry.name))); } catch {}
+  }
+  out.sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
+  return out;
+}
+
+export async function readGitOplogChange(tracker, opId) {
+  if (!isGitOplogChangeTrackerAvailable(tracker)) throw new Error('Git change oplog is not available for this session');
+  const id = String(opId || '').trim();
+  if (!id) throw new Error('Missing change id');
+  return readJson(path.join(tracker.opsDir, `${id}.json`));
+}
+
+export async function readGitOplogPatch(tracker, opId) {
+  const op = await readGitOplogChange(tracker, opId);
+  return fs.readFile(op.patchPath, 'utf8');
+}
+
+export async function undoGitOplogChange(tracker, opId) {
+  if (!isGitOplogChangeTrackerAvailable(tracker)) throw new Error('Git change oplog is not available for this session');
+  const op = await readGitOplogChange(tracker, opId);
+  if (op.revertedAt) {
+    return { ok: false, alreadyReverted: true, changeSetId: op.id, message: 'Change already reverted' };
+  }
+  const patch = await fs.readFile(op.patchPath, 'utf8');
+  try {
+    await runGit(['apply', '-R', '--check', '--whitespace=nowarn'], {
+      cwd: tracker.workspaceRoot,
+      input: patch,
+      timeoutMs: 120_000
+    });
+  } catch (error) {
+    throw new Error(`Cannot undo this change cleanly because newer edits conflict with it. Undo newer changes first, or revert it manually. ${error?.message || ''}`.trim());
+  }
+  await runGit(['apply', '-R', '--whitespace=nowarn'], {
+    cwd: tracker.workspaceRoot,
+    input: patch,
+    timeoutMs: 120_000
+  });
+  op.revertedAt = new Date().toISOString();
+  await writeJson(path.join(tracker.opsDir, `${op.id}.json`), op);
+  return { ok: true, changeSetId: op.id };
+}

package/src/core/non-git-backup.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizePath } from './string-utils.js';
+
+function normalizeRelativePath(value) {
+  const text = normalizePath(String(value || '').trim()).replace(/:\d+(?:-\d+)?$/, '');
+  if (!text || text === '.' || path.isAbsolute(text) || text.startsWith('../')) return '';
+  return text;
+}
+
+function safeBackupRelativePath(relativePath) {
+  return normalizeRelativePath(relativePath)
+    .split('/')
+    .map((part) => part.replace(/[<>:"\\|?*\x00-\x1F]/g, '_'))
+    .join('/');
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export async function createNonGitBackupManager({ workspaceRoot = process.cwd(), sessionId } = {}) {
+  const root = path.resolve(workspaceRoot);
+  const id = String(sessionId || '').trim();
+  if (!id) return null;
+  const backupRoot = path.join(root, '.codemini', 'backups', 'sessions', id);
+  const filesRoot = path.join(backupRoot, 'files');
+  const manifestPath = path.join(backupRoot, 'manifest.json');
+  await fs.mkdir(filesRoot, { recursive: true });
+  const manifest = await readJson(manifestPath, {
+    version: 1,
+    sessionId: id,
+    createdAt: new Date().toISOString(),
+    files: {}
+  });
+
+  async function backupOnce(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) return { ok: false, reason: 'invalid-path' };
+    const existing = manifest.files?.[normalized];
+    if (existing) {
+      return { ...existing, ok: true, reused: true, created: false };
+    }
+
+    const target = path.resolve(root, normalized);
+    const rel = path.relative(root, target);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      return { ok: false, path: normalized, reason: 'outside-workspace' };
+    }
+
+    let stat;
+    try {
+      stat = await fs.stat(target);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      const entry = {
+        path: normalized,
+        existed: false,
+        backupPath: '',
+        backupRelativePath: '',
+        createdAt: new Date().toISOString()
+      };
+      manifest.files[normalized] = entry;
+      await writeJson(manifestPath, manifest);
+      return { ...entry, ok: true, reused: false, created: false };
+    }
+
+    if (!stat.isFile()) {
+      const entry = {
+        path: normalized,
+        existed: true,
+        backupPath: '',
+        backupRelativePath: '',
+        skipped: true,
+        reason: stat.isDirectory() ? 'directory' : 'not-file',
+        createdAt: new Date().toISOString()
+      };
+      manifest.files[normalized] = entry;
+      await writeJson(manifestPath, manifest);
+      return { ...entry, ok: true, reused: false, created: false };
+    }
+
+    const safeRelative = safeBackupRelativePath(normalized);
+    const backupPath = path.join(filesRoot, safeRelative);
+    await fs.mkdir(path.dirname(backupPath), { recursive: true });
+    await fs.copyFile(target, backupPath);
+    const entry = {
+      path: normalized,
+      existed: true,
+      backupPath,
+      backupRelativePath: normalizePath(path.relative(root, backupPath)),
+      createdAt: new Date().toISOString()
+    };
+    manifest.files[normalized] = entry;
+    await writeJson(manifestPath, manifest);
+    return { ...entry, ok: true, reused: false, created: true };
+  }
+
+  return {
+    mode: 'non-git-backup',
+    workspaceRoot: root,
+    sessionId: id,
+    backupRoot,
+    manifestPath,
+    backupOnce
+  };
+}