metame-cli 1.4.34 → 1.5.1

package/scripts/daemon-agent-tools.js

@@ -1,5 +1,15 @@
 'use strict';
 
+const {
+  createAgentId,
+  ensureClaudeMdSoulImport,
+  ensureAgentLayer,
+  repairAgentLayer,
+  refreshMemorySnapshot,
+  buildMemorySnapshotContent,
+  normalizeEngine: normalizeLayerEngine,
+} = require('./agent-layer');
+
 function createAgentTools(deps) {
   const {
     fs,
@@ -31,13 +41,35 @@ function createAgentTools(deps) {
     return (String(agentName || '').replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase() || String(chatId));
   }
 
+  function ensureAgentMetadata({ cfg, projectKey, project, safeName, resolvedDir, engine }) {
+    const agentId = String(project && project.agent_id ? project.agent_id : createAgentId({
+      projectKey,
+      agentName: safeName,
+      cwd: resolvedDir,
+    }));
+    const ensured = ensureAgentLayer({
+      agentId,
+      projectKey,
+      agentName: safeName,
+      workspaceDir: resolvedDir,
+      engine: normalizeLayerEngine(engine || (project && project.engine)),
+      aliases: [safeName],
+      homeDir: HOME,
+    });
+    cfg.projects[projectKey] = {
+      ...cfg.projects[projectKey],
+      agent_id: ensured.agentId,
+    };
+    return ensured;
+  }
+
   function ensureAdapterConfig(cfg, adapterKey) {
     if (!cfg[adapterKey]) cfg[adapterKey] = {};
     if (!cfg[adapterKey].allowed_chat_ids) cfg[adapterKey].allowed_chat_ids = [];
     if (!cfg[adapterKey].chat_agent_map) cfg[adapterKey].chat_agent_map = {};
   }
 
-  async function bindAgentToChat(chatId, agentName, workspaceDir, { force = false } = {}) {
+  async function bindAgentToChat(chatId, agentName, workspaceDir, { force = false, engine = null } = {}) {
     try {
       const safeName = sanitizeText(agentName, 120);
       if (!safeName) return { ok: false, error: 'agentName is required' };
@@ -49,6 +81,7 @@ function createAgentTools(deps) {
 
       const projectKey = toProjectKey(safeName, chatId);
       let resolvedDir = resolveWorkspaceDir(workspaceDir);
+      const normalizedEngine = engine ? normalizeLayerEngine(engine) : null;
 
       if (!resolvedDir) {
         const existing = cfg.projects[projectKey];
@@ -80,7 +113,13 @@ function createAgentTools(deps) {
       cfg[adapterKey].chat_agent_map[String(chatId)] = projectKey;
       const existed = !!cfg.projects[projectKey];
       if (!existed) {
-        cfg.projects[projectKey] = { name: safeName, cwd: resolvedDir, nicknames: [safeName] };
+        cfg.projects[projectKey] = {
+          name: safeName,
+          cwd: resolvedDir,
+          nicknames: [safeName],
+          agent_id: createAgentId({ projectKey, agentName: safeName, cwd: resolvedDir }),
+          ...(normalizedEngine === 'codex' ? { engine: 'codex' } : {}),
+        };
       } else {
         const nicknames = Array.isArray(cfg.projects[projectKey].nicknames)
           ? cfg.projects[projectKey].nicknames
@@ -91,9 +130,20 @@ function createAgentTools(deps) {
           name: safeName,
           cwd: resolvedDir,
           nicknames,
+          agent_id: cfg.projects[projectKey].agent_id || createAgentId({ projectKey, agentName: safeName, cwd: resolvedDir }),
+          ...(normalizedEngine === 'codex' ? { engine: 'codex' } : {}),
         };
       }
 
+      const agentLayer = ensureAgentMetadata({
+        cfg,
+        projectKey,
+        project: cfg.projects[projectKey],
+        safeName,
+        resolvedDir,
+        engine: normalizedEngine,
+      });
+
       writeConfigSafe(cfg);
       backupConfig();
 
@@ -106,6 +156,7 @@ function createAgentTools(deps) {
           cwd: resolvedDir,
           isNewProject: !existed,
           project: cfg.projects[projectKey],
+          agent: agentLayer,
         },
       };
     } catch (e) {
@@ -127,6 +178,7 @@ function createAgentTools(deps) {
       const claudeMdPath = path.join(cwd, 'CLAUDE.md');
       if (!fs.existsSync(claudeMdPath)) {
         fs.writeFileSync(claudeMdPath, `## Agent 角色\n\n${safeDelta}\n`, 'utf8');
+        try { ensureClaudeMdSoulImport(cwd); } catch { /* non-critical */ }
         return { ok: true, data: { created: true, merged: false, path: claudeMdPath } };
       }
 
@@ -169,14 +221,16 @@ ${safeDelta}
         cleanOutput = cleanOutput.replace(/^```[a-zA-Z]*\n/, '').replace(/\n```$/, '');
       }
       fs.writeFileSync(claudeMdPath, cleanOutput, 'utf8');
+      try { ensureClaudeMdSoulImport(cwd); } catch { /* non-critical */ }
       return { ok: true, data: { created: false, merged: true, path: claudeMdPath } };
     } catch (e) {
       return { ok: false, error: e.message };
     }
   }
 
-  async function createNewWorkspaceAgent(agentName, workspaceDir, roleDescription, chatId, { skipChatBinding = false } = {}) {
+  async function createNewWorkspaceAgent(agentName, workspaceDir, roleDescription, chatId, { skipChatBinding = false, engine = null } = {}) {
     let bindData;
+    const normalizedEngine = engine ? normalizeLayerEngine(engine) : null;
 
     if (skipChatBinding) {
       // Create the project entry without touching chat_agent_map
@@ -192,19 +246,40 @@ ${safeDelta}
       const projectKey = toProjectKey(safeName, chatId);
       const existed = !!cfg.projects[projectKey];
       if (!existed) {
-        cfg.projects[projectKey] = { name: safeName, cwd: resolvedDir, nicknames: [safeName] };
-        writeConfigSafe(cfg);
-        backupConfig();
+        cfg.projects[projectKey] = {
+          name: safeName,
+          cwd: resolvedDir,
+          nicknames: [safeName],
+          agent_id: createAgentId({ projectKey, agentName: safeName, cwd: resolvedDir }),
+          ...(normalizedEngine === 'codex' ? { engine: 'codex' } : {}),
+        };
+      } else {
+        cfg.projects[projectKey] = {
+          ...cfg.projects[projectKey],
+          ...(normalizedEngine === 'codex' ? { engine: 'codex' } : {}),
+          agent_id: cfg.projects[projectKey].agent_id || createAgentId({ projectKey, agentName: safeName, cwd: resolvedDir }),
+        };
       }
+      const agentLayer = ensureAgentMetadata({
+        cfg,
+        projectKey,
+        project: cfg.projects[projectKey],
+        safeName,
+        resolvedDir,
+        engine: normalizedEngine,
+      });
+      writeConfigSafe(cfg);
+      backupConfig();
       bindData = {
         projectKey,
         cwd: resolvedDir,
         isNewProject: !existed,
         chatId: null,      // not bound to any chat
         project: cfg.projects[projectKey],
+        agent: agentLayer,
       };
     } else {
-      const bindResult = await bindAgentToChat(chatId, agentName, workspaceDir);
+      const bindResult = await bindAgentToChat(chatId, agentName, workspaceDir, { engine: normalizedEngine });
       if (!bindResult.ok) return bindResult;
       bindData = bindResult.data;
     }
@@ -223,6 +298,10 @@ ${safeDelta}
       };
     }
 
+    // editAgentRoleDefinition may have just created CLAUDE.md for the first time.
+    // Ensure @SOUL.md import is present so Claude auto-loads soul on every future session.
+    try { ensureClaudeMdSoulImport(bindData.cwd); } catch { /* non-critical */ }
+
     return {
       ok: true,
       data: { ...bindData, role: roleResult.data },
@@ -281,12 +360,89 @@ ${safeDelta}
     }
   }
 
+  /**
+   * Lazy-migration repair: given a workspace directory, ensure the agent soul layer
+   * (~/.metame/agents/<id>/, SOUL.md, MEMORY.md) exists and is wired up.
+   * Persists agent_id back to daemon.yaml if it was missing.
+   * Safe to call repeatedly — idempotent.
+   */
+  async function repairAgentSoul(workspaceDir) {
+    try {
+      const cwd = resolveWorkspaceDir(workspaceDir);
+      if (!cwd) return { ok: false, error: 'workspaceDir is required' };
+      if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+        return { ok: false, error: `workspaceDir not found: ${cwd}` };
+      }
+
+      const cfg = loadConfig();
+      let projectKey = null;
+      let project = null;
+      for (const [key, p] of Object.entries(cfg.projects || {})) {
+        if (!p || !p.cwd) continue;
+        const pCwd = normalizeCwd ? normalizeCwd(p.cwd) : p.cwd;
+        const r1 = path.resolve(pCwd);
+        const r2 = path.resolve(cwd);
+        const isMatch = process.platform === 'win32'
+          ? r1.toLowerCase() === r2.toLowerCase()
+          : r1 === r2;
+        if (isMatch) {
+          projectKey = key;
+          project = p;
+          break;
+        }
+      }
+      if (!projectKey) {
+        return { ok: false, error: `No registered agent found for: ${cwd}. Run /agent bind first.` };
+      }
+
+      const ensured = repairAgentLayer(projectKey, project, HOME);
+      if (!ensured) return { ok: false, error: 'repairAgentLayer returned null' };
+
+      // Persist agent_id back to config if it was missing
+      if (!project.agent_id) {
+        cfg.projects[projectKey] = { ...cfg.projects[projectKey], agent_id: ensured.agentId };
+        writeConfigSafe(cfg);
+        backupConfig();
+      }
+
+      return {
+        ok: true,
+        data: {
+          projectKey,
+          agentId: ensured.agentId,
+          views: ensured.views
+            ? Object.fromEntries(Object.entries(ensured.views).map(([k, v]) => [k, v.mode]))
+            : null,
+        },
+      };
+    } catch (e) {
+      return { ok: false, error: e.message };
+    }
+  }
+
+  /**
+   * Refresh memory-snapshot.md from fresh session+fact data.
+   * Called by the engine after first-message of a session; also callable directly.
+   */
+  async function updateMemorySnapshot(agentId, sessions = [], facts = []) {
+    try {
+      if (!agentId) return { ok: false, error: 'agentId is required' };
+      const content = buildMemorySnapshotContent(sessions, facts);
+      const ok = refreshMemorySnapshot(agentId, content, HOME);
+      return { ok, error: ok ? null : 'agent directory not found or not yet created' };
+    } catch (e) {
+      return { ok: false, error: e.message };
+    }
+  }
+
   return {
     bindAgentToChat,
     createNewWorkspaceAgent,
     editAgentRoleDefinition,
     listAllAgents,
     unbindCurrentAgent,
+    repairAgentSoul,
+    updateMemorySnapshot,
   };
 }
 

package/scripts/daemon-bridges.js

@@ -1,5 +1,8 @@
 'use strict';
 
+let userAcl = null;
+try { userAcl = require('./daemon-user-acl'); } catch { /* optional */ }
+
 function createBridgeStarter(deps) {
   const {
     fs,
@@ -15,6 +18,52 @@ function createBridgeStarter(deps) {
     pendingActivations,  // optional — used to show smart activation hint
   } = deps;
 
+  async function sendAclReply(bot, chatId, text) {
+    if (!text) return;
+    try {
+      if (bot.sendMarkdown) await bot.sendMarkdown(chatId, text);
+      else await bot.sendMessage(chatId, text.replace(/[*_`]/g, ''));
+    } catch { /* non-fatal */ }
+  }
+
+  function normalizeSenderId(senderId) {
+    if (senderId === undefined || senderId === null) return null;
+    const text = String(senderId).trim();
+    return text || null;
+  }
+
+  async function applyUserAcl({ bot, chatId, text, config, senderId, bypassAcl }) {
+    const trimmed = String(text || '').trim();
+    const normalizedSenderId = normalizeSenderId(senderId);
+    if (!trimmed || bypassAcl || !userAcl) {
+      return { blocked: false, readOnly: false, senderId: normalizedSenderId };
+    }
+
+    let userCtx;
+    try {
+      userCtx = userAcl.resolveUserCtx(normalizedSenderId, config || {});
+    } catch {
+      return { blocked: false, readOnly: false, senderId: normalizedSenderId };
+    }
+
+    const userCmd = userAcl.handleUserCommand(trimmed, userCtx);
+    if (userCmd && userCmd.handled) {
+      await sendAclReply(bot, chatId, userCmd.reply);
+      return { blocked: true, readOnly: !!userCtx.readOnly, senderId: normalizedSenderId };
+    }
+
+    const publicCmds = Array.isArray(userAcl.PUBLIC_COMMANDS) ? userAcl.PUBLIC_COMMANDS : [];
+    const isPublic = publicCmds.includes(trimmed.toLowerCase());
+    const action = userAcl.classifyCommandAction(trimmed);
+    const allowed = isPublic || (typeof userCtx.can === 'function' && userCtx.can(action));
+    if (!allowed) {
+      await sendAclReply(bot, chatId, `⚠️ 当前权限不足（角色: ${userCtx.role}）\n命令类型: ${action}\n请联系管理员授权。`);
+      return { blocked: true, readOnly: true, senderId: normalizedSenderId };
+    }
+
+    return { blocked: false, readOnly: !!userCtx.readOnly, senderId: normalizedSenderId };
+  }
+
   // Returns the best pending activation for a given chatId (excludes self-created)
   function getPendingActivationForChat(chatId) {
     if (!pendingActivations || pendingActivations.size === 0) return null;
@@ -67,12 +116,26 @@ function createBridgeStarter(deps) {
             if (update.callback_query) {
               const cb = update.callback_query;
               const chatId = cb.message && cb.message.chat.id;
+              const senderId = cb.from && cb.from.id ? String(cb.from.id) : null;
               bot.answerCallback(cb.id).catch(() => { });
               if (chatId && cb.data) {
                 const liveCfg = loadConfig();
                 const allowedIds = (liveCfg.telegram && liveCfg.telegram.allowed_chat_ids) || [];
                 if (!allowedIds.includes(chatId)) continue;
-                handleCommand(bot, chatId, cb.data, liveCfg, executeTaskByName).catch(e => {
+                const isBindCmd = cb.data.startsWith('/agent bind')
+                  || cb.data.startsWith('/agent-bind-dir')
+                  || cb.data.startsWith('/browse bind')
+                  || cb.data === '/activate';
+                const acl = await applyUserAcl({
+                  bot,
+                  chatId,
+                  text: cb.data,
+                  config: liveCfg,
+                  senderId,
+                  bypassAcl: !allowedIds.includes(chatId) && !!isBindCmd,
+                });
+                if (acl.blocked) continue;
+                handleCommand(bot, chatId, cb.data, liveCfg, executeTaskByName, acl.senderId, acl.readOnly).catch(e => {
                   log('ERROR', `Telegram callback handler error: ${e.message}`);
                 });
               }
@@ -83,6 +146,7 @@ function createBridgeStarter(deps) {
 
             const msg = update.message;
             const chatId = msg.chat.id;
+            const senderId = msg.from && msg.from.id ? String(msg.from.id) : null;
 
             const liveCfg = loadConfig();
             const allowedIds = (liveCfg.telegram && liveCfg.telegram.allowed_chat_ids) || [];
@@ -93,7 +157,8 @@ function createBridgeStarter(deps) {
               || trimmedText.startsWith('/browse bind')
               || trimmedText === '/activate'
             );
-            if (!allowedIds.includes(chatId) && !isBindCmd) {
+            const isAllowedChat = allowedIds.includes(chatId);
+            if (!isAllowedChat && !isBindCmd) {
               log('WARN', `Rejected message from unauthorized chat: ${chatId}`);
               bot.sendMessage(chatId, unauthorizedMsg(chatId)).catch(() => {});
               continue;
@@ -108,6 +173,15 @@ function createBridgeStarter(deps) {
               const fileId = msg.document ? msg.document.file_id : msg.photo[msg.photo.length - 1].file_id;
               const fileName = msg.document ? msg.document.file_name : `photo_${Date.now()}.jpg`;
               const caption = msg.caption || '';
+              const acl = await applyUserAcl({
+                bot,
+                chatId,
+                text: caption || '[file-upload]',
+                config: liveCfg,
+                senderId,
+                bypassAcl: !isAllowedChat && !!isBindCmd,
+              });
+              if (acl.blocked) continue;
 
               const session = getSession(chatId);
               const cwd = session?.cwd || HOME;
@@ -123,7 +197,7 @@ function createBridgeStarter(deps) {
                   ? `User uploaded a file to the project: ${destPath}\nUser says: "${caption}"`
                   : `User uploaded a file to the project: ${destPath}\nAcknowledge receipt. Only read the file if the user asks you to.`;
 
-                handleCommand(bot, chatId, prompt, liveCfg, executeTaskByName).catch(e => {
+                handleCommand(bot, chatId, prompt, liveCfg, executeTaskByName, acl.senderId, acl.readOnly).catch(e => {
                   log('ERROR', `Telegram file handler error: ${e.message}`);
                 });
               } catch (err) {
@@ -134,7 +208,17 @@ function createBridgeStarter(deps) {
             }
 
             if (msg.text) {
-              handleCommand(bot, chatId, msg.text.trim(), liveCfg, executeTaskByName).catch(e => {
+              const text = msg.text.trim();
+              const acl = await applyUserAcl({
+                bot,
+                chatId,
+                text,
+                config: liveCfg,
+                senderId,
+                bypassAcl: !isAllowedChat && !!isBindCmd,
+              });
+              if (acl.blocked) continue;
+              handleCommand(bot, chatId, text, liveCfg, executeTaskByName, acl.senderId, acl.readOnly).catch(e => {
                 log('ERROR', `Telegram handler error: ${e.message}`);
               });
             }
@@ -182,27 +266,24 @@ function createBridgeStarter(deps) {
           || trimmedText.startsWith('/browse bind')
           || trimmedText === '/activate'
         );
-        if (!allowedIds.includes(chatId) && !isBindCmd) {
+        const isAllowedChat = allowedIds.includes(chatId);
+        if (!isAllowedChat && !isBindCmd) {
           log('WARN', `Feishu: rejected message from ${chatId}`);
           const msg = unauthorizedMsg(chatId);
           (bot.sendMarkdown ? bot.sendMarkdown(chatId, msg) : bot.sendMessage(chatId, msg)).catch(() => {});
           return;
         }
 
-        const operatorIds = (liveCfg.feishu && liveCfg.feishu.operator_ids) || [];
-        if (operatorIds.length > 0 && senderId && !operatorIds.includes(senderId) && !isBindCmd) {
-          log('INFO', `Feishu: read-only message from non-operator ${senderId} in ${chatId}: ${(text || '').slice(0, 50)}`);
-          if (text && text.startsWith('/')) {
-            await (bot.sendMarkdown ? bot.sendMarkdown(chatId, '⚠️ 该操作需要授权，请联系管理员。') : bot.sendMessage(chatId, '⚠️ 该操作需要授权，请联系管理员。'));
-            return;
-          }
-          if (text) {
-            await handleCommand(bot, chatId, text, liveCfg, executeTaskByName, senderId, true);
-          }
-          return;
-        }
-
         if (fileInfo && fileInfo.fileKey) {
+          const acl = await applyUserAcl({
+            bot,
+            chatId,
+            text: text || '[file-upload]',
+            config: liveCfg,
+            senderId,
+            bypassAcl: !isAllowedChat && !!isBindCmd,
+          });
+          if (acl.blocked) return;
           log('INFO', `Feishu file from ${chatId}: ${fileInfo.fileName} (key: ${fileInfo.fileKey}, msgId: ${fileInfo.messageId}, type: ${fileInfo.msgType})`);
           const session = getSession(chatId);
           const cwd = session?.cwd || HOME;
@@ -218,7 +299,7 @@ function createBridgeStarter(deps) {
               ? `User uploaded a file to the project: ${destPath}\nUser says: "${text}"`
               : `User uploaded a file to the project: ${destPath}\nAcknowledge receipt. Only read the file if the user asks you to.`;
 
-            await handleCommand(bot, chatId, prompt, liveCfg, executeTaskByName);
+            await handleCommand(bot, chatId, prompt, liveCfg, executeTaskByName, acl.senderId, acl.readOnly);
           } catch (err) {
             log('ERROR', `Feishu file download failed: ${err.message}`);
             await bot.sendMessage(chatId, `❌ Download failed: ${err.message}`);
@@ -227,6 +308,15 @@ function createBridgeStarter(deps) {
         }
 
         if (text) {
+          const acl = await applyUserAcl({
+            bot,
+            chatId,
+            text,
+            config: liveCfg,
+            senderId,
+            bypassAcl: !isAllowedChat && !!isBindCmd,
+          });
+          if (acl.blocked) return;
           log('INFO', `Feishu message from ${chatId}: ${text.slice(0, 50)}`);
           const parentId = event?.message?.parent_id;
           if (parentId) {
@@ -238,7 +328,7 @@ function createBridgeStarter(deps) {
               log('INFO', `Session restored via reply: ${mapped.id.slice(0, 8)} (${path.basename(mapped.cwd)})`);
             }
           }
-          await handleCommand(bot, chatId, text, liveCfg, executeTaskByName, senderId);
+          await handleCommand(bot, chatId, text, liveCfg, executeTaskByName, acl.senderId, acl.readOnly);
         }
       });
 

package/scripts/daemon-checkpoints.js

@@ -1,7 +1,9 @@
 'use strict';
 
 function createCheckpointUtils(deps) {
-  const { execSync, path, log } = deps;
+  const { execSync, execFile, path, log } = deps;
+  const { promisify } = require('util');
+  const execFileAsync = execFile ? promisify(execFile) : null;
 
   const CHECKPOINT_PREFIX = '[metame-checkpoint]';
   const MAX_CHECKPOINTS = 20;
@@ -35,19 +37,22 @@ function createCheckpointUtils(deps) {
     return message.replace(CHECKPOINT_PREFIX, '').trim();
   }
 
+  // On Windows, git.exe is a console app — windowsHide:true prevents flash
+  const WIN_HIDE = process.platform === 'win32' ? { windowsHide: true } : {};
+
   function gitCheckpoint(cwd, label) {
     try {
-      execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore' });
-      execSync('git add -A', { cwd, stdio: 'ignore', timeout: 5000 });
-      const status = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 5000 }).trim();
+      execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore', ...WIN_HIDE });
+      execSync('git add -A', { cwd, stdio: 'ignore', timeout: 5000, ...WIN_HIDE });
+      const status = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 5000, ...WIN_HIDE }).trim();
       if (!status) return null;
       const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
       const safeLabel = label
         ? ' Before: ' + label.replace(/["\n\r]/g, ' ').slice(0, 60).trim()
         : '';
       const msg = `${CHECKPOINT_PREFIX}${safeLabel} (${ts})`;
-      execSync(`git commit -m "${msg}" --no-verify`, { cwd, stdio: 'ignore', timeout: 10000 });
-      const hash = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 3000 }).trim();
+      execSync(`git commit -m "${msg}" --no-verify`, { cwd, stdio: 'ignore', timeout: 10000, ...WIN_HIDE });
+      const hash = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 3000, ...WIN_HIDE }).trim();
       log('INFO', `Git checkpoint: ${hash.slice(0, 8)} in ${path.basename(cwd)}${safeLabel}`);
       return hash;
     } catch {
@@ -55,11 +60,34 @@ function createCheckpointUtils(deps) {
     }
   }
 
+  // Async version: runs git commands without blocking the event loop.
+  // Call fire-and-forget before spawning Claude; completes well before Claude's first file write.
+  async function gitCheckpointAsync(cwd, label) {
+    if (!execFileAsync) return gitCheckpoint(cwd, label); // fallback
+    try {
+      await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 3000, ...WIN_HIDE });
+      await execFileAsync('git', ['add', '-A'], { cwd, timeout: 5000, ...WIN_HIDE });
+      const { stdout: status } = await execFileAsync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8', timeout: 5000, ...WIN_HIDE });
+      if (!status.trim()) return null;
+      const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      const safeLabel = label
+        ? ' Before: ' + label.replace(/["\n\r]/g, ' ').slice(0, 60).trim()
+        : '';
+      const msg = `${CHECKPOINT_PREFIX}${safeLabel} (${ts})`;
+      await execFileAsync('git', ['commit', '-m', msg, '--no-verify'], { cwd, timeout: 10000, ...WIN_HIDE });
+      const { stdout: hash } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', timeout: 3000, ...WIN_HIDE });
+      log('INFO', `Git checkpoint: ${hash.trim().slice(0, 8)} in ${path.basename(cwd)}${safeLabel}`);
+      return hash.trim();
+    } catch {
+      return null;
+    }
+  }
+
   function listCheckpoints(cwd, limit = 20) {
     try {
       const raw = execSync(
         `git log --fixed-strings --oneline --all --grep="${CHECKPOINT_PREFIX}" -n ${limit} --format="%H %s"`,
-        { cwd, encoding: 'utf8', timeout: 5000 }
+        { cwd, encoding: 'utf8', timeout: 5000, ...WIN_HIDE }
       ).trim();
       if (!raw) return [];
       return raw.split('\n').map(line => {
@@ -81,6 +109,7 @@ function createCheckpointUtils(deps) {
     cpExtractTimestamp,
     cpDisplayLabel,
     gitCheckpoint,
+    gitCheckpointAsync,
     listCheckpoints,
     cleanupCheckpoints,
   };