@notis_ai/cli 0.2.0-beta.165.1 → 0.2.0-beta.167.1

package/dist/skill-sync-worker.mjs

@@ -1881,10 +1881,34 @@ async function extractZipToDirectory(zipPath, destinationDir) {
     await fs.rm(destinationDir, { recursive: true, force: true });
     await fs.mkdir(path.dirname(destinationDir), { recursive: true });
     await fs.cp(sourceDir, destinationDir, { recursive: true });
+    return await listRelativeFiles(destinationDir);
   } finally {
     await fs.rm(extractRoot, { recursive: true, force: true });
   }
 }
+async function listRelativeFiles(dirPath) {
+  try {
+    const files = await listFilesRecursive(dirPath);
+    return files.map((filePath) => toPosixRelativePath(dirPath, filePath)).sort();
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+function toPosixRelativePath(rootDir, filePath) {
+  return path.relative(rootDir, filePath).split(path.sep).join("/");
+}
+async function preserveUnmanagedFiles(existingDir, stagingDir, previouslyApplied) {
+  const managed = previouslyApplied ? new Set(previouslyApplied) : null;
+  for (const existingFile of await listFilesRecursive(existingDir)) {
+    const relativePath = toPosixRelativePath(existingDir, existingFile);
+    if (managed?.has(relativePath)) continue;
+    const stagedPath = path.join(stagingDir, ...relativePath.split("/"));
+    if (await pathExists(stagedPath)) continue;
+    await fs.mkdir(path.dirname(stagedPath), { recursive: true });
+    await fs.copyFile(existingFile, stagedPath);
+  }
+}
 async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -1893,7 +1917,7 @@ async function pathExists(targetPath) {
     return false;
   }
 }
-async function replaceSkillDirectoryAtomically(skillDir, populateDir) {
+async function replaceSkillDirectoryAtomically(skillDir, populateDir, preserve) {
   const parentDir = path.dirname(skillDir);
   const skillName = path.basename(skillDir);
   await fs.mkdir(parentDir, { recursive: true });
@@ -1909,6 +1933,9 @@ async function replaceSkillDirectoryAtomically(skillDir, populateDir) {
   let cleanupError = null;
   try {
     await populateDir(stagingDir);
+    if (preserve && await pathExists(skillDir)) {
+      await preserveUnmanagedFiles(skillDir, stagingDir, preserve.previouslyApplied);
+    }
     if (await pathExists(skillDir)) {
       await fs.rename(skillDir, backupDir);
       movedExisting = true;
@@ -1956,11 +1983,12 @@ async function createSkillBundleBase64(skill) {
     await fs.rm(zipPath, { force: true });
   }
 }
-async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PATHS) {
+async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PATHS, options = {}) {
   const skillDir = path.join(
     paths.skillsDir,
     safeName(skill.name, paths.skillsDir)
   );
+  const preserve = { previouslyApplied: options.previouslyApplied };
   if (bundleBytes?.length) {
     const bundlePath = path.join(
       os.tmpdir(),
@@ -1968,8 +1996,11 @@ async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PA
     );
     try {
       await fs.writeFile(bundlePath, bundleBytes);
-      await extractZipToDirectory(bundlePath, skillDir);
-      return true;
+      let appliedFiles = [];
+      await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
+        appliedFiles = await extractZipToDirectory(bundlePath, stagingDir);
+      }, preserve);
+      return { written: true, appliedFiles };
     } finally {
       await fs.rm(bundlePath, { force: true });
     }
@@ -1983,6 +2014,7 @@ async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PA
         `Synced bundle for "${skill.name}" is missing SKILL.md or SKILLS.md`
       );
     }
+    const appliedFiles = [];
     await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
       for (const bundleFile of skill.bundle_files || []) {
         const filePath = resolveSkillBundleFilePath(
@@ -1994,9 +2026,10 @@ async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PA
           filePath,
           Buffer.from(bundleFile.content_b64, "base64")
         );
+        appliedFiles.push(toPosixRelativePath(stagingDir, filePath));
       }
-    });
-    return true;
+    }, preserve);
+    return { written: true, appliedFiles: appliedFiles.sort() };
   }
   await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
     await fs.writeFile(
@@ -2004,8 +2037,8 @@ async function writeCloudSkillToDisk(skill, bundleBytes, paths = DEFAULT_SYNC_PA
       skill.skill_md ?? "",
       "utf8"
     );
-  });
-  return true;
+  }, preserve);
+  return { written: true, appliedFiles: ["SKILL.md"] };
 }
 async function requestJson(url, jwt, options = {}) {
   const response = await fetch(url, {
@@ -2399,7 +2432,7 @@ async function writeCloudSkillWithBundleFallback(skill, dependencies) {
       const bundleBytes = await dependencies.downloadSkillBundle(skill.skill_source_url);
       const wroteBundleToDisk = await dependencies.writeCloudSkillToDisk(skill, bundleBytes);
       if (wroteBundleToDisk) {
-        return true;
+        return wroteBundleToDisk;
       }
       dependencies.onWarning?.(
         `Bundle sync for "${skill.name}" produced no local changes, falling back to SKILL.md payload.`,
@@ -2511,12 +2544,20 @@ function collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillN
   }
   return applied;
 }
-function buildSyncState(pullResponse, localSkills, lastSyncedAt, verifiedAgentLinks = {}, failedContentNames = /* @__PURE__ */ new Set(), appliedRevisions = {}) {
+function collectAppliedFiles(pullResponse, previousState, appliedFilesByName) {
+  const applied = {};
+  for (const skill of selectCloudSkillsToApply(pullResponse.skills)) {
+    applied[skill.name] = appliedFilesByName[skill.name] ?? previousState.skills[skill.name]?.appliedFiles;
+  }
+  return applied;
+}
+function buildSyncState(pullResponse, localSkills, lastSyncedAt, verifiedAgentLinks = {}, failedContentNames = /* @__PURE__ */ new Set(), appliedRevisions = {}, appliedFiles = {}) {
   const localSkillMap = toSkillMap(localSkills);
   const skills = Object.fromEntries(
     selectCloudSkillsToApply(pullResponse.skills).map((skill) => {
       const localSkill = localSkillMap.get(skill.name);
       const appliedCloudFolderHash = appliedRevisions[skill.name];
+      const appliedFileList = appliedFiles[skill.name];
       return [
         skill.name,
         {
@@ -2527,6 +2568,7 @@ function buildSyncState(pullResponse, localSkills, lastSyncedAt, verifiedAgentLi
           cloudUpdatedAt: skill.updated_at,
           ...!failedContentNames.has(skill.name) && !skill.skill_source_url ? { cloudContentHash: cloudContentHash(skill) } : {},
           ...appliedCloudFolderHash !== void 0 ? { appliedCloudFolderHash } : {},
+          ...appliedFileList !== void 0 ? { appliedFiles: appliedFileList } : {},
           syncedAt: lastSyncedAt || (/* @__PURE__ */ new Date()).toISOString()
         }
       ];
@@ -2582,7 +2624,7 @@ function applyLegacyFirstRunState(localSkills, scopedState, legacyState) {
     skills: migratedSkills
   };
 }
-async function writePulledSkillsToScopedMirror(pullResponse, localSkills, previousState, syncPaths, deps, failures = [], writtenSkillNames = /* @__PURE__ */ new Set()) {
+async function writePulledSkillsToScopedMirror(pullResponse, localSkills, previousState, syncPaths, deps, failures = [], writtenSkillNames = /* @__PURE__ */ new Set(), appliedFilesByName = {}) {
   const localSkillMap = toSkillMap(localSkills);
   const warnSkillSync = (message, error) => {
     console.warn(`[Notis] ${message}`, error);
@@ -2592,13 +2634,21 @@ async function writePulledSkillsToScopedMirror(pullResponse, localSkills, previo
     if (!shouldWriteCloudSkill(cloudSkill, localSkillMap, previousState)) {
       continue;
     }
-    if (await writeCloudSkillWithBundleFallback(cloudSkill, {
+    const outcome = await writeCloudSkillWithBundleFallback(cloudSkill, {
       downloadSkillBundle: deps.downloadSkillBundle,
-      writeCloudSkillToDisk: (skill, bundleBytes) => deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths),
+      writeCloudSkillToDisk: (skill, bundleBytes) => deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths, {
+        // What the last write put there. Everything else in the folder was
+        // produced locally and survives this one.
+        previouslyApplied: previousState.skills[skill.name]?.appliedFiles
+      }),
       onWarning: warnSkillSync
-    })) {
+    });
+    if (outcome) {
       downloaded += 1;
       writtenSkillNames.add(cloudSkill.name);
+      if (typeof outcome === "object" && Array.isArray(outcome.appliedFiles)) {
+        appliedFilesByName[cloudSkill.name] = outcome.appliedFiles;
+      }
     } else {
       failures.push({ name: cloudSkill.name, error: "Skill content could not be downloaded or written; sync will retry" });
     }
@@ -2769,6 +2819,7 @@ async function runSkillSync(serverUrl, jwt, dependencies = {}, options = {}) {
   }
   const failedDownloads = [];
   const writtenSkillNames = /* @__PURE__ */ new Set();
+  const appliedFilesByName = {};
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
@@ -2776,7 +2827,8 @@ async function runSkillSync(serverUrl, jwt, dependencies = {}, options = {}) {
     syncPaths,
     deps,
     failedDownloads,
-    writtenSkillNames
+    writtenSkillNames,
+    appliedFilesByName
   );
   const finalLocalSkills = (await deps.scanLocalSkills(syncPaths)).filter((skill) => !BASE_SKILL_NAMES.has(skill.name));
   const symlinkResult = await deps.syncSymlinks(
@@ -2793,7 +2845,8 @@ async function runSkillSync(serverUrl, jwt, dependencies = {}, options = {}) {
       lastSyncedAt,
       verifiedLinks,
       new Set(failedDownloads.map((item) => item.name)),
-      collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames)
+      collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames),
+      collectAppliedFiles(pullResponse, previousState, appliedFilesByName)
     ),
     syncPaths
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.165.1",
+  "version": "0.2.0-beta.167.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/src/runtime/skill-sync/index.ts

@@ -231,6 +231,24 @@ function collectAppliedCloudRevisions(
   return applied;
 }
 
+/**
+ * The files each folder's last successful write put on disk: this run's list for the
+ * skills we just wrote, the previously recorded one otherwise. Missing means "no
+ * record", which keeps local files rather than deleting what cannot be attributed.
+ */
+function collectAppliedFiles(
+  pullResponse: SyncPullResponse,
+  previousState: NotisSyncState,
+  appliedFilesByName: Record<string, string[]>,
+): Record<string, string[] | undefined> {
+  const applied: Record<string, string[] | undefined> = {};
+  for (const skill of selectCloudSkillsToApply(pullResponse.skills)) {
+    applied[skill.name] = appliedFilesByName[skill.name]
+      ?? previousState.skills[skill.name]?.appliedFiles;
+  }
+  return applied;
+}
+
 function buildSyncState(
   pullResponse: SyncPullResponse,
   localSkills: LocalSkill[],
@@ -238,6 +256,7 @@ function buildSyncState(
   verifiedAgentLinks: Record<string, Partial<AgentTargets>> = {},
   failedContentNames: ReadonlySet<string> = new Set(),
   appliedRevisions: AppliedCloudRevisions = {},
+  appliedFiles: Record<string, string[] | undefined> = {},
 ): NotisSyncState {
   const localSkillMap = toSkillMap(localSkills);
   // The same row selection the writer used, so the state describes the revision that
@@ -246,6 +265,7 @@ function buildSyncState(
     selectCloudSkillsToApply(pullResponse.skills).map((skill) => {
       const localSkill = localSkillMap.get(skill.name);
       const appliedCloudFolderHash = appliedRevisions[skill.name];
+      const appliedFileList = appliedFiles[skill.name];
       return [
         skill.name,
         {
@@ -257,6 +277,7 @@ function buildSyncState(
           ...(!failedContentNames.has(skill.name) && !skill.skill_source_url
             ? { cloudContentHash: cloudContentHash(skill) } : {}),
           ...(appliedCloudFolderHash !== undefined ? { appliedCloudFolderHash } : {}),
+          ...(appliedFileList !== undefined ? { appliedFiles: appliedFileList } : {}),
           syncedAt: lastSyncedAt || new Date().toISOString(),
         },
       ];
@@ -342,6 +363,7 @@ async function writePulledSkillsToScopedMirror(
   >,
   failures: SkillSyncFailure[] = [],
   writtenSkillNames: Set<string> = new Set(),
+  appliedFilesByName: Record<string, string[]> = {},
 ): Promise<number> {
   const localSkillMap = toSkillMap(localSkills);
   const warnSkillSync = (message: string, error: unknown): void => {
@@ -354,16 +376,22 @@ async function writePulledSkillsToScopedMirror(
       continue;
     }
 
-    if (
-      await writeCloudSkillWithBundleFallback(cloudSkill, {
-        downloadSkillBundle: deps.downloadSkillBundle,
-        writeCloudSkillToDisk: (skill, bundleBytes) =>
-          deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths),
-        onWarning: warnSkillSync,
-      })
-    ) {
+    const outcome = await writeCloudSkillWithBundleFallback(cloudSkill, {
+      downloadSkillBundle: deps.downloadSkillBundle,
+      writeCloudSkillToDisk: (skill, bundleBytes) =>
+        deps.writeCloudSkillToDisk(skill, bundleBytes, syncPaths, {
+          // What the last write put there. Everything else in the folder was
+          // produced locally and survives this one.
+          previouslyApplied: previousState.skills[skill.name]?.appliedFiles,
+        }),
+      onWarning: warnSkillSync,
+    });
+    if (outcome) {
       downloaded += 1;
       writtenSkillNames.add(cloudSkill.name);
+      if (typeof outcome === "object" && Array.isArray(outcome.appliedFiles)) {
+        appliedFilesByName[cloudSkill.name] = outcome.appliedFiles;
+      }
     } else {
       failures.push({ name: cloudSkill.name, error: "Skill content could not be downloaded or written; sync will retry" });
     }
@@ -425,6 +453,7 @@ export async function materializeCloudSkillsForLocalShell(
   const localSkills = await deps.scanLocalSkills(syncPaths);
   const failedDownloads: SkillSyncFailure[] = [];
   const writtenSkillNames = new Set<string>();
+  const appliedFilesByName: Record<string, string[]> = {};
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
@@ -433,6 +462,7 @@ export async function materializeCloudSkillsForLocalShell(
     deps,
     failedDownloads,
     writtenSkillNames,
+    appliedFilesByName,
   );
   const finalLocalSkills = await deps.scanLocalSkills(syncPaths);
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
@@ -465,6 +495,7 @@ export async function materializeCloudSkillsForLocalShell(
     pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks,
     new Set(failedDownloads.map(item => item.name)),
     collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames),
+    collectAppliedFiles(pullResponse, previousState, appliedFilesByName),
   );
   // Pull-only refresh is not an upload acknowledgement. Keep content baselines
   // unless we actually wrote cloud content, and retain cloud-missing entries so
@@ -701,6 +732,7 @@ export async function runSkillSync(
 
   const failedDownloads: SkillSyncFailure[] = [];
   const writtenSkillNames = new Set<string>();
+  const appliedFilesByName: Record<string, string[]> = {};
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
@@ -709,6 +741,7 @@ export async function runSkillSync(
     deps,
     failedDownloads,
     writtenSkillNames,
+    appliedFilesByName,
   );
 
   const finalLocalSkills = (await deps.scanLocalSkills(syncPaths))
@@ -729,6 +762,7 @@ export async function runSkillSync(
       verifiedLinks,
       new Set(failedDownloads.map(item => item.name)),
       collectAppliedCloudRevisions(pullResponse, previousState, writtenSkillNames),
+      collectAppliedFiles(pullResponse, previousState, appliedFilesByName),
     ),
     syncPaths,
   );

package/src/runtime/skill-sync/local-scanner.ts

@@ -6,7 +6,7 @@ import os from "os";
 import path from "path";
 import { promisify } from "util";
 
-import type { CloudSkill, LocalSkill, NotisSyncState } from "./types";
+import type { CloudSkill, LocalSkill, NotisSyncState, SkillWriteOutcome } from "./types";
 
 const HOME_DIR = os.homedir();
 const execFileAsync = promisify(execFile);
@@ -860,7 +860,7 @@ async function createZipFromDirectory(directoryPath: string): Promise<string> {
 async function extractZipToDirectory(
   zipPath: string,
   destinationDir: string,
-): Promise<void> {
+): Promise<string[]> {
   const extractRoot = await fs.mkdtemp(
     path.join(os.tmpdir(), "notis-skill-extract-"),
   );
@@ -889,11 +889,56 @@ async function extractZipToDirectory(
     await fs.rm(destinationDir, { recursive: true, force: true });
     await fs.mkdir(path.dirname(destinationDir), { recursive: true });
     await fs.cp(sourceDir, destinationDir, { recursive: true });
+    return await listRelativeFiles(destinationDir);
   } finally {
     await fs.rm(extractRoot, { recursive: true, force: true });
   }
 }
 
+async function listRelativeFiles(dirPath: string): Promise<string[]> {
+  try {
+    const files = await listFilesRecursive(dirPath);
+    return files.map((filePath) => toPosixRelativePath(dirPath, filePath)).sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function toPosixRelativePath(rootDir: string, filePath: string): string {
+  return path.relative(rootDir, filePath).split(path.sep).join("/");
+}
+
+/**
+ * Carry local-only files across a cloud write. A skill that writes while it runs
+ * (a run ledger under its own folder) would otherwise lose that work every time the
+ * cloud content changed, because the write replaces the whole directory.
+ *
+ * Selective, not a blanket merge:
+ * - a path the incoming content provides always wins;
+ * - a path the previous write applied and the cloud has now dropped stays deleted,
+ *   so upstream removals still propagate;
+ * - anything else is local and is kept.
+ *
+ * With no record of the previous write (state written before this existed) nothing
+ * can be attributed to the cloud, so local files are kept rather than destroyed.
+ */
+async function preserveUnmanagedFiles(
+  existingDir: string,
+  stagingDir: string,
+  previouslyApplied?: readonly string[],
+): Promise<void> {
+  const managed = previouslyApplied ? new Set(previouslyApplied) : null;
+  for (const existingFile of await listFilesRecursive(existingDir)) {
+    const relativePath = toPosixRelativePath(existingDir, existingFile);
+    if (managed?.has(relativePath)) continue;
+    const stagedPath = path.join(stagingDir, ...relativePath.split("/"));
+    if (await pathExists(stagedPath)) continue;
+    await fs.mkdir(path.dirname(stagedPath), { recursive: true });
+    await fs.copyFile(existingFile, stagedPath);
+  }
+}
+
 async function pathExists(targetPath: string): Promise<boolean> {
   try {
     await fs.access(targetPath);
@@ -906,6 +951,7 @@ async function pathExists(targetPath: string): Promise<boolean> {
 async function replaceSkillDirectoryAtomically(
   skillDir: string,
   populateDir: (stagingDir: string) => Promise<void>,
+  preserve?: { previouslyApplied?: readonly string[] },
 ): Promise<void> {
   const parentDir = path.dirname(skillDir);
   const skillName = path.basename(skillDir);
@@ -926,6 +972,10 @@ async function replaceSkillDirectoryAtomically(
   try {
     await populateDir(stagingDir);
 
+    if (preserve && (await pathExists(skillDir))) {
+      await preserveUnmanagedFiles(skillDir, stagingDir, preserve.previouslyApplied);
+    }
+
     if (await pathExists(skillDir)) {
       await fs.rename(skillDir, backupDir);
       movedExisting = true;
@@ -986,11 +1036,13 @@ export async function writeCloudSkillToDisk(
   skill: CloudSkill,
   bundleBytes?: Buffer,
   paths: SkillSyncPaths = DEFAULT_SYNC_PATHS,
-): Promise<boolean> {
+  options: { previouslyApplied?: readonly string[] } = {},
+): Promise<SkillWriteOutcome | false> {
   const skillDir = path.join(
     paths.skillsDir,
     safeName(skill.name, paths.skillsDir),
   );
+  const preserve = { previouslyApplied: options.previouslyApplied };
 
   if (bundleBytes?.length) {
     const bundlePath = path.join(
@@ -999,8 +1051,11 @@ export async function writeCloudSkillToDisk(
     );
     try {
       await fs.writeFile(bundlePath, bundleBytes);
-      await extractZipToDirectory(bundlePath, skillDir);
-      return true;
+      let appliedFiles: string[] = [];
+      await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
+        appliedFiles = await extractZipToDirectory(bundlePath, stagingDir);
+      }, preserve);
+      return { written: true, appliedFiles };
     } finally {
       await fs.rm(bundlePath, { force: true });
     }
@@ -1019,6 +1074,7 @@ export async function writeCloudSkillToDisk(
         `Synced bundle for "${skill.name}" is missing SKILL.md or SKILLS.md`,
       );
     }
+    const appliedFiles: string[] = [];
     await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
       for (const bundleFile of skill.bundle_files || []) {
         const filePath = resolveSkillBundleFilePath(
@@ -1030,9 +1086,10 @@ export async function writeCloudSkillToDisk(
           filePath,
           Buffer.from(bundleFile.content_b64, "base64"),
         );
+        appliedFiles.push(toPosixRelativePath(stagingDir, filePath));
       }
-    });
-    return true;
+    }, preserve);
+    return { written: true, appliedFiles: appliedFiles.sort() };
   }
 
   await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
@@ -1041,6 +1098,6 @@ export async function writeCloudSkillToDisk(
       skill.skill_md ?? "",
       "utf8",
     );
-  });
-  return true;
+  }, preserve);
+  return { written: true, appliedFiles: ["SKILL.md"] };
 }

package/src/runtime/skill-sync/types.ts

@@ -14,6 +14,10 @@ export interface SyncedSkill {
   cloudUpdatedAt?: string;
   /** Content accepted on disk; independent of server-specific folder hash formats. */
   cloudContentHash?: string;
+  /** Relative paths the last successful write put in this folder. Anything else in
+   * the folder was created locally (a running skill's output) and survives the next
+   * cloud write; anything listed here that the cloud later drops is deleted. */
+  appliedFiles?: string[];
   /** `skill_folder_hash` of the cloud revision a successful write actually applied.
    * The server may compute that hash with a different construction than the local
    * folder hash (app-published skills do), so only cloud-to-cloud comparison tells
@@ -28,6 +32,13 @@ export interface NotisSyncState {
   skills: Record<string, SyncedSkill>;
 }
 
+/** A successful write, plus the paths it put on disk so the next one can tell
+ * cloud-managed files apart from whatever ran inside the folder since. */
+export interface SkillWriteOutcome {
+  written: true;
+  appliedFiles: string[];
+}
+
 export interface LocalSkill {
   name: string;
   skillMd: string;

package/src/runtime/skill-sync/write-cloud-skill.ts

@@ -1,21 +1,21 @@
-import type { CloudSkill } from './types';
+import type { CloudSkill, SkillWriteOutcome } from './types';
 
 interface WriteCloudSkillDependencies {
   downloadSkillBundle: (bundleUrl: string) => Promise<Buffer>;
-  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<boolean>;
+  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<SkillWriteOutcome | boolean>;
   onWarning?: (message: string, error: unknown) => void;
 }
 
 export async function writeCloudSkillWithBundleFallback(
   skill: CloudSkill,
   dependencies: WriteCloudSkillDependencies,
-): Promise<boolean> {
+): Promise<SkillWriteOutcome | boolean> {
   if (skill.skill_source_url) {
     try {
       const bundleBytes = await dependencies.downloadSkillBundle(skill.skill_source_url);
       const wroteBundleToDisk = await dependencies.writeCloudSkillToDisk(skill, bundleBytes);
       if (wroteBundleToDisk) {
-        return true;
+        return wroteBundleToDisk;
       }
 
       dependencies.onWarning?.(