@notis_ai/cli 0.2.18 → 0.2.20

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

@@ -6,10 +6,13 @@ import os from "os";
 import path from "path";
 import { promisify } from "util";
 
-import type { CloudSkill, LocalSkill, NotisSyncState } from "./types";
+import type { BundleFile, CloudSkill, LocalSkill, NotisSyncState, SkillWriteOutcome } from "./types";
+import { NATIVE_IDENTITY_FILE, assertNativePull, checkedNativeIdentity, isNativeSkill,
+  nativeFileDigest, nativeFrontmatterName, type NativeSkillIdentity } from './native-identity';
 
 const HOME_DIR = os.homedir();
 const execFileAsync = promisify(execFile);
+class NativeSkillIdentityError extends Error {}
 
 export const AGENTS_DIR = path.join(HOME_DIR, ".agents");
 export const LEGACY_AGENTS_SKILLS_DIR = path.join(AGENTS_DIR, "skills");
@@ -45,6 +48,9 @@ const EXCLUDED_TOP_LEVEL_ROOT_NAMES = new Set([
 ]);
 
 export interface SkillSyncPaths {
+  /** Explicit process-independent home for a confined sync invocation. */
+  homeDir?: string;
+  isolatedNamespace?: string;
   agentsDir: string;
   syncRoot: string;
   legacySkillsDir: string;
@@ -96,14 +102,21 @@ function sanitizePathSegment(value: string): string {
 export function getSkillSyncPathsForUser(
   authUserId: string,
   agentsDir: string = AGENTS_DIR,
+  namespace?: string | null,
+  syncHome?: string,
 ): SkillSyncPaths {
   const safeUserId = sanitizePathSegment(authUserId);
-  const resolvedAgentsDir = path.resolve(agentsDir);
-  const syncRoot = getDefaultSyncRootForAgentsDir(resolvedAgentsDir);
-  const userRoot = path.join(syncRoot, "users", safeUserId);
+  const homeDir = syncHome ? path.resolve(syncHome) : undefined;
+  const resolvedAgentsDir = homeDir ? path.join(homeDir, '.agents') : path.resolve(agentsDir);
+  const syncRoot = homeDir ? path.join(homeDir, '.notis', 'skills') : getDefaultSyncRootForAgentsDir(resolvedAgentsDir);
+  const userRoot = namespace
+    ? path.join(syncRoot, 'environments', sanitizePathSegment(namespace), 'users', safeUserId)
+    : path.join(syncRoot, "users", safeUserId);
   const legacyUserRoot = path.join(resolvedAgentsDir, "notis", "users", safeUserId);
 
   return {
+    ...(homeDir ? { homeDir } : {}),
+    ...(namespace ? { isolatedNamespace: sanitizePathSegment(namespace) } : {}),
     agentsDir: resolvedAgentsDir,
     syncRoot,
     legacySkillsDir: path.join(resolvedAgentsDir, "skills"),
@@ -163,17 +176,29 @@ async function readJsonFile<T>(filePath: string): Promise<T | null> {
   }
 }
 
-async function listFilesRecursive(dirPath: string): Promise<string[]> {
+// Interpreter caches a script run leaves beside itself are not skill content: they
+// must neither mark a skill as changed nor ship in its bundle (app bundling applies
+// the same rule).
+const IGNORED_SKILL_DIRECTORIES = new Set(["__pycache__", ".pytest_cache"]);
+
+function isIgnoredSkillEntry(entry: Dirent): boolean {
+  if (entry.name === ".DS_Store") return true;
+  if (entry.isDirectory()) return IGNORED_SKILL_DIRECTORIES.has(entry.name);
+  return /\.py[co]$/i.test(entry.name);
+}
+
+async function listFilesRecursive(dirPath: string, rootPath = dirPath, strictLinks = false): Promise<string[]> {
   const entries = await fs.readdir(dirPath, { withFileTypes: true });
   const nested = await Promise.all(
     entries.map(async (entry) => {
-      if (entry.name === ".DS_Store") {
+      if (isIgnoredSkillEntry(entry) || (dirPath === rootPath && entry.name === NATIVE_IDENTITY_FILE)) {
         return [];
       }
 
       const fullPath = path.join(dirPath, entry.name);
+      if (strictLinks && entry.isSymbolicLink()) throw new Error('Native Skill bundles cannot contain symbolic links.');
       if (entry.isDirectory()) {
-        return listFilesRecursive(fullPath);
+        return listFilesRecursive(fullPath, rootPath, strictLinks);
       }
 
       if (entry.isFile()) {
@@ -326,17 +351,17 @@ function defaultTopLevelSkillSources(
     { label: "agents", root: paths.legacySkillsDir, priority: 2 },
     {
       label: "codex",
-      root: path.join(HOME_DIR, ".codex", "skills"),
+      root: path.join(paths.homeDir || HOME_DIR, ".codex", "skills"),
       priority: 3,
     },
     {
       label: "cursor",
-      root: path.join(HOME_DIR, ".cursor", "skills"),
+      root: path.join(paths.homeDir || HOME_DIR, ".cursor", "skills"),
       priority: 4,
     },
     {
       label: "claude",
-      root: path.join(HOME_DIR, ".claude", "skills"),
+      root: path.join(paths.homeDir || HOME_DIR, ".claude", "skills"),
       priority: 5,
     },
   );
@@ -680,6 +705,7 @@ export async function scanLocalSkills(
   await ensureCanonicalSkillsDir(paths);
 
   const sourceUrls = await readSkillLock(paths);
+  const previousState = await readSyncState(paths);
   const entries = await fs.readdir(paths.skillsDir, { withFileTypes: true });
   const skills: Array<LocalSkill | null> = await Promise.all(
     entries.map(async (entry) => {
@@ -692,7 +718,17 @@ export async function scanLocalSkills(
 
       const skillDir = path.join(paths.skillsDir, entry.name);
       const skillMdPath = path.join(skillDir, "SKILL.md");
-
+      let marker: string | null = null;
+      // Classify provenance BEFORE reading potentially unavailable content.
+      // Failure to scan a managed folder is not evidence that it is absent.
+      try { marker = await fs.readFile(path.join(skillDir, NATIVE_IDENTITY_FILE), 'utf8'); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw new NativeSkillIdentityError('Native Skill provenance could not be read; existing files were retained.');
+        }
+      }
+      const knownNative = marker !== null || Boolean(previousState.skills[entry.name]?.nativeReference)
+        || Object.values(previousState.nativeHistory || {}).some(row => row.names.includes(entry.name));
       try {
         const skillMd = await fs.readFile(skillMdPath, "utf8");
         const { description } = parseFrontMatter(skillMd);
@@ -704,11 +740,27 @@ export async function scanLocalSkills(
           folderHash,
           directoryPath: skillDir,
         };
+        if (marker !== null) {
+          let identity: NativeSkillIdentity;
+          try { identity = checkedNativeIdentity(JSON.parse(marker)); }
+          catch { throw new NativeSkillIdentityError('Native Skill provenance is unreadable; do not upload it as a new Skill.'); }
+          let current = true;
+          for (const [name, expected] of Object.entries(identity.files)) {
+            try { if (nativeFileDigest(await fs.readFile(resolveSkillBundleFilePath(skillDir, name))) !== expected) current = false; }
+            catch { current = false; }
+          }
+          const editedName = nativeFrontmatterName(skillMd);
+          Object.assign(skill, { cloudId: identity.cloudId, nativeReference: identity.reference,
+            nativeScope: identity.scope, nativeBaseFolderHash: identity.folderHash, nativeFilesCurrent: current,
+            displayName: editedName && editedName !== identity.frontmatterName ? editedName : identity.displayName });
+        }
         if (sourceUrls[entry.name]) {
           skill.sourceUrl = sourceUrls[entry.name];
         }
         return skill;
-      } catch {
+      } catch (error) {
+        if (error instanceof NativeSkillIdentityError) throw error;
+        if (knownNative) throw new NativeSkillIdentityError('Native Skill files could not be read; existing files were retained.');
         return null;
       }
     }),
@@ -725,6 +777,11 @@ function normalizeSyncState(
   if (!state || state.version !== 1 || typeof state.skills !== "object") {
     return null;
   }
+  if (state.nativeHistory && (typeof state.nativeHistory !== 'object' || Array.isArray(state.nativeHistory)
+      || Object.values(state.nativeHistory).some(row => !row || !Array.isArray(row.names)
+        || row.names.some(name => typeof name !== 'string')))) {
+    throw new Error('Native Skill sync provenance is unreadable; existing files were retained.');
+  }
   const normalizeStoredAgentTargets = (
     targets: Partial<NotisSyncState["skills"][string]["agentTargets"]> | null | undefined,
   ): NotisSyncState["skills"][string]["agentTargets"] => ({
@@ -736,6 +793,7 @@ function normalizeSyncState(
 
   return {
     version: 1,
+    ...(state.nativeHistory ? { nativeHistory: state.nativeHistory } : {}),
     lastSyncedAt:
       typeof state.lastSyncedAt === "string" ? state.lastSyncedAt : null,
     skills: Object.fromEntries(
@@ -839,28 +897,65 @@ async function createZipFromDirectory(directoryPath: string): Promise<string> {
     os.tmpdir(),
     `notis-skill-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`,
   );
-  const parentDir = path.dirname(directoryPath);
   const directoryName = path.basename(directoryPath);
+  // Zip a copy holding exactly the files the folder hash covers, so ignored
+  // caches never ship.
+  const stagingRoot = await fs.mkdtemp(path.join(os.tmpdir(), "notis-skill-bundle-"));
+  try {
+    const stagedDir = path.join(stagingRoot, directoryName);
+    for (const filePath of await listFilesRecursive(directoryPath)) {
+      const target = path.join(stagedDir, path.relative(directoryPath, filePath));
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.copyFile(filePath, target);
+    }
+    await fs.mkdir(stagedDir, { recursive: true });
+
+    if (process.platform === "win32") {
+      // Windows PowerShell's Compress-Archive writes entry names with
+      // backslashes, which unzip on the cloud computer as literal file names
+      // ("cached\\SKILL.md"). bsdtar, shipped in System32 since Windows 10
+      // 1803, writes the forward slashes the zip format requires. Use the
+      // system copy explicitly: on a Git Bash PATH, "tar" resolves to GNU tar,
+      // which cannot write zip archives.
+      const systemTar = path.join(
+        process.env.SystemRoot || "C:\\Windows",
+        "System32",
+        "tar.exe",
+      );
+      if (await pathExists(systemTar)) {
+        await execFileAsync(systemTar, [
+          "-c",
+          "--format",
+          "zip",
+          "-f",
+          zipPath,
+          "-C",
+          stagingRoot,
+          directoryName,
+        ]);
+        return zipPath;
+      }
+      await execFileAsync("powershell.exe", [
+        "-NoProfile",
+        "-Command",
+        `Compress-Archive -Path '${stagedDir.replace(/'/g, "''")}' -DestinationPath '${zipPath.replace(/'/g, "''")}' -Force`,
+      ]);
+      return zipPath;
+    }
 
-  if (process.platform === "win32") {
-    await execFileAsync("powershell.exe", [
-      "-NoProfile",
-      "-Command",
-      `Compress-Archive -Path '${directoryPath.replace(/'/g, "''")}' -DestinationPath '${zipPath.replace(/'/g, "''")}' -Force`,
-    ]);
+    await execFileAsync("zip", ["-qry", zipPath, directoryName], {
+      cwd: stagingRoot,
+    });
     return zipPath;
+  } finally {
+    await fs.rm(stagingRoot, { recursive: true, force: true });
   }
-
-  await execFileAsync("zip", ["-qry", zipPath, directoryName], {
-    cwd: parentDir,
-  });
-  return zipPath;
 }
 
 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 +984,62 @@ 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[],
+  strictConflicts = false,
+): 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)) {
+      if (strictConflicts && !(await fs.readFile(existingFile)).equals(await fs.readFile(stagedPath))) {
+        throw new Error('An incoming native Skill file conflicts with a local file. Local files were retained.');
+      }
+      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 +1052,7 @@ async function pathExists(targetPath: string): Promise<boolean> {
 async function replaceSkillDirectoryAtomically(
   skillDir: string,
   populateDir: (stagingDir: string) => Promise<void>,
+  preserve?: { previouslyApplied?: readonly string[]; expectedFolderHash?: string; native?: boolean; legacyBaseline?: boolean },
 ): Promise<void> {
   const parentDir = path.dirname(skillDir);
   const skillName = path.basename(skillDir);
@@ -924,11 +1071,44 @@ async function replaceSkillDirectoryAtomically(
   let cleanupError: Error | null = null;
 
   try {
+    if (preserve?.native && preserve.expectedFolderHash === undefined) {
+      let existing = false;
+      try { await fs.lstat(skillDir); existing = true; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (existing) throw new Error('Existing native Skill files need a readable baseline before replacement.');
+    }
+    if (preserve?.expectedFolderHash !== undefined
+        && (!await pathExists(skillDir) || await computeFolderHash(skillDir) !== preserve.expectedFolderHash)) {
+      throw new Error('Local Skill files changed before sync; the newer local edits were retained.');
+    }
     await populateDir(stagingDir);
 
+    if (preserve && (await pathExists(skillDir))) {
+      await preserveUnmanagedFiles(skillDir, stagingDir, preserve.previouslyApplied,
+        preserve.native && !preserve.legacyBaseline);
+    }
+
+    if (preserve?.native) {
+      const markerPath = path.join(stagingDir, NATIVE_IDENTITY_FILE);
+      const marker = checkedNativeIdentity(JSON.parse(await fs.readFile(markerPath, 'utf8')));
+      marker.folderHash = await computeFolderHash(stagingDir);
+      await fs.writeFile(markerPath, JSON.stringify(marker), { mode: 0o600 });
+    }
+
+    if (preserve?.expectedFolderHash !== undefined
+        && (!await pathExists(skillDir) || await computeFolderHash(skillDir) !== preserve.expectedFolderHash)) {
+      throw new Error('Local Skill files changed during sync; the newer local edits were retained.');
+    }
+
     if (await pathExists(skillDir)) {
       await fs.rename(skillDir, backupDir);
       movedExisting = true;
+      if (preserve?.native && preserve.expectedFolderHash === undefined) {
+        throw new Error('Native Skill files appeared during sync; existing files were retained.');
+      }
+      if (preserve?.expectedFolderHash !== undefined && await computeFolderHash(backupDir) !== preserve.expectedFolderHash) {
+        throw new Error('Local Skill files changed before publication; the newer local edits were retained.');
+      }
     }
 
     await fs.rename(stagingDir, skillDir);
@@ -982,15 +1162,38 @@ export async function createSkillBundleBase64(
   }
 }
 
+export async function captureNativeSkillFiles(skill: LocalSkill): Promise<BundleFile[]> {
+  const hash = createHash('sha256');
+  const files: BundleFile[] = [];
+  for (const filePath of await listFilesRecursive(skill.directoryPath, skill.directoryPath, true)) {
+    const relative = path.relative(skill.directoryPath, filePath);
+    const bytes = await fs.readFile(filePath);
+    hash.update(relative); hash.update('\0'); hash.update(bytes); hash.update('\0');
+    files.push({ path: relative.split(path.sep).join('/'), content_b64: bytes.toString('base64') });
+  }
+  if (hash.digest('hex') !== skill.folderHash) throw new Error('Local Skill files changed before upload. Sync again with the current files.');
+  return files;
+}
+
 export async function writeCloudSkillToDisk(
   skill: CloudSkill,
   bundleBytes?: Buffer,
   paths: SkillSyncPaths = DEFAULT_SYNC_PATHS,
-): Promise<boolean> {
+  options: { previouslyApplied?: readonly string[]; expectedFolderHash?: string; legacyBaseline?: boolean } = {},
+): Promise<SkillWriteOutcome | false> {
+  if (isNativeSkill(skill)) {
+    assertNativePull({ skills: [{ ...skill, name: 'native-' + skill.id }], skill_sync_protocol: 2, sync_scope: skill.native_scope,
+      sync_enabled: true, last_synced_at: null });
+    if (bundleBytes?.length) throw new Error('Native Skills require their verified complete file response.');
+  }
   const skillDir = path.join(
     paths.skillsDir,
     safeName(skill.name, paths.skillsDir),
   );
+  const preserve = { previouslyApplied: options.previouslyApplied, expectedFolderHash: options.expectedFolderHash,
+    native: isNativeSkill(skill),
+    // An unchanged legacy folder upgrading in place: shared files take the cloud version.
+    legacyBaseline: isNativeSkill(skill) && options.legacyBaseline === true && options.expectedFolderHash !== undefined };
 
   if (bundleBytes?.length) {
     const bundlePath = path.join(
@@ -999,8 +1202,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 +1225,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 +1237,18 @@ export async function writeCloudSkillToDisk(
           filePath,
           Buffer.from(bundleFile.content_b64, "base64"),
         );
+        appliedFiles.push(toPosixRelativePath(stagingDir, filePath));
       }
-    });
-    return true;
+      if (skill.native_reference) {
+        const identity: NativeSkillIdentity = { schema: 1, cloudId: skill.id, reference: skill.native_reference,
+          displayName: skill.display_name || skill.name, frontmatterName: nativeFrontmatterName(skill.skill_md || ''),
+          scope: skill.native_scope!, folderHash: await computeFolderHash(stagingDir),
+          files: Object.fromEntries((skill.bundle_files || []).map(file => [file.path, nativeFileDigest(Buffer.from(file.content_b64, 'base64'))])) };
+        await fs.writeFile(path.join(stagingDir, NATIVE_IDENTITY_FILE), JSON.stringify(identity), { mode: 0o600 });
+        appliedFiles.push(NATIVE_IDENTITY_FILE);
+      }
+    }, preserve);
+    return { written: true, appliedFiles: appliedFiles.sort() };
   }
 
   await replaceSkillDirectoryAtomically(skillDir, async (stagingDir) => {
@@ -1041,6 +1257,6 @@ export async function writeCloudSkillToDisk(
       skill.skill_md ?? "",
       "utf8",
     );
-  });
-  return true;
+  }, preserve);
+  return { written: true, appliedFiles: ["SKILL.md"] };
 }

package/src/runtime/skill-sync/native-identity.ts

@@ -0,0 +1,102 @@
+import type { CloudSkill, NativeSkillReference, SyncedSkill, SyncPullResponse } from './types';
+import { createHash } from 'node:crypto';
+
+export const NATIVE_IDENTITY_FILE = '.notis-native-skill.json';
+export interface NativeSkillIdentity {
+  schema: 1;
+  cloudId: string;
+  reference: NativeSkillReference;
+  displayName: string;
+  frontmatterName: string;
+  scope: string;
+  folderHash: string;
+  files: Record<string, string>;
+}
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+
+export function checkedNativeReference(value: unknown, cloudId?: string): NativeSkillReference {
+  const reference = value as NativeSkillReference;
+  if (!reference || typeof reference !== 'object' || Array.isArray(reference)
+      || Object.keys(reference).sort().join(',') !== 'access_revision,kind,skill_id,version'
+      || reference.kind !== 'native_standalone_skill' || !UUID.test(reference.skill_id)
+      || (cloudId !== undefined && reference.skill_id !== cloudId)
+      || !Number.isSafeInteger(reference.access_revision) || reference.access_revision < 0
+      || !reference.version || Object.keys(reference.version).sort().join(',') !== 'digest,revision'
+      || !Number.isSafeInteger(reference.version.revision) || reference.version.revision < 1
+      || !/^[a-f0-9]{64}$/.test(reference.version.digest)) {
+    throw new Error('Native Skill identity is unavailable. Refresh before syncing.');
+  }
+  return structuredClone(reference);
+}
+
+export function nativeDirectory(reference: NativeSkillReference): string {
+  return 'native-' + checkedNativeReference(reference).skill_id;
+}
+
+export function sameNativeReference(left?: NativeSkillReference, right?: NativeSkillReference): boolean {
+  return Boolean(left && right && left.skill_id === right.skill_id
+    && left.access_revision === right.access_revision && left.version.revision === right.version.revision
+    && left.version.digest === right.version.digest);
+}
+
+export function isNativeSkill(skill: CloudSkill): boolean {
+  return skill.source === 'native' || skill.native_reference !== undefined;
+}
+
+export function assertNativePull(response: SyncPullResponse): void {
+  const ids = new Set<string>();
+  for (const skill of response.skills) {
+    if (!isNativeSkill(skill)) continue;
+    const reference = checkedNativeReference(skill.native_reference, skill.id);
+    if (response.skill_sync_protocol !== 2 || skill.name !== nativeDirectory(reference) || ids.has(skill.id)
+        || !/^[a-f0-9]{64}$/.test(response.sync_scope || '') || skill.native_scope !== response.sync_scope
+        || !Array.isArray(skill.bundle_files) || skill.bundle_hydration_failed || typeof skill.skill_md !== 'string') {
+      throw new Error('Native Skill inventory is incomplete. Existing local files were retained.');
+    }
+    const paths = new Set<string>();
+    let entrypoint = false;
+    for (const file of skill.bundle_files) {
+      if (typeof file.path !== 'string' || typeof file.content_b64 !== 'string'
+          || file.path.startsWith('/') || file.path.includes('\\') || file.path.includes('\0')
+          || file.path.split('/').some(part => !part || part === '.' || part === '..')
+          || paths.has(file.path.toLowerCase()) || file.path.toLowerCase() === NATIVE_IDENTITY_FILE) {
+        throw new Error('Native Skill bundle has a conflicting managed path.');
+      }
+      paths.add(file.path.toLowerCase());
+      if (file.path === 'SKILL.md') {
+        entrypoint = Buffer.from(file.content_b64, 'base64').equals(Buffer.from(skill.skill_md, 'utf8'));
+      }
+    }
+    if (!entrypoint) throw new Error('Native Skill instructions and files do not match.');
+    ids.add(skill.id);
+  }
+}
+
+export function nativeFileDigest(bytes: Buffer): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function nativeFrontmatterName(markdown: string): string {
+  const header = markdown.match(/^---\s*\n([\s\S]*?)\n---/);
+  return header?.[1].match(/^name\s*:\s*(.+)$/m)?.[1].trim().replace(/^['"]|['"]$/g, '') || '';
+}
+
+export function checkedNativeIdentity(value: unknown): NativeSkillIdentity {
+  const identity = value as NativeSkillIdentity;
+  if (!identity || identity.schema !== 1 || typeof identity.cloudId !== 'string'
+      || typeof identity.displayName !== 'string' || typeof identity.frontmatterName !== 'string'
+      || !/^[a-f0-9]{64}$/.test(identity.scope) || !/^[a-f0-9]{64}$/.test(identity.folderHash)
+      || !identity.files || !Object.keys(identity.files).includes('SKILL.md')
+      || Object.entries(identity.files).some(([name, hash]) => name.startsWith('/') || name.includes('\\')
+        || name.split('/').some(part => !part || part === '.' || part === '..') || !/^[a-f0-9]{64}$/.test(hash))) {
+    throw new Error('Native Skill provenance is incomplete. Existing files were retained.');
+  }
+  return { ...identity, reference: checkedNativeReference(identity.reference, identity.cloudId) };
+}
+
+export function nativeState(skill: CloudSkill): Partial<SyncedSkill> {
+  if (!isNativeSkill(skill)) return {};
+  return { nativeReference: checkedNativeReference(skill.native_reference, skill.id),
+    ...(skill.native_settings ? { nativeSettingsRevision: skill.native_settings.revision } : {}),
+    nativeDisplayName: skill.display_name || skill.name, nativeScope: skill.native_scope, nativeUnavailable: false };
+}

package/src/runtime/skill-sync/native-plan.ts

@@ -0,0 +1,70 @@
+import type { CloudSkill, LocalSkill, NotisSyncState, SyncPullResponse } from './types';
+import { checkedNativeReference, isNativeSkill, sameNativeReference } from './native-identity';
+
+/** Folder names may change; existing managed cloud identity may not. */
+export function bindNativeFolders(response: SyncPullResponse, locals: LocalSkill[], state: NotisSyncState): SyncPullResponse {
+  const nativeIds = new Set(response.skills.filter(isNativeSkill).map(skill => skill.id));
+  for (const entry of Object.values(state.skills)) if (entry.nativeReference || entry.nativeUnavailable) nativeIds.add(entry.cloudId);
+  const byId = new Map<string, LocalSkill>();
+  for (const local of locals) {
+    const id = local.cloudId || state.skills[local.name]?.cloudId;
+    if (!id || (!nativeIds.has(id) && !local.nativeReference)) continue;
+    if (local.nativeReference) checkedNativeReference(local.nativeReference, id);
+    if (byId.has(id)) throw new Error('Two local folders claim the same native Skill. Keep both copies and resolve the conflict.');
+    byId.set(id, local);
+  }
+  const skills = response.skills.map(skill => isNativeSkill(skill) && byId.has(skill.id)
+    ? { ...skill, name: byId.get(skill.id)!.name } : skill);
+  for (const skill of skills.filter(isNativeSkill)) {
+    if (skills.some(other => other.id !== skill.id && other.name === skill.name)) {
+      throw new Error('A native Skill and another Skill share a local folder. Existing files were retained.');
+    }
+  }
+  return { ...response, skills };
+}
+
+export function previousNativeState(state: NotisSyncState, skill: CloudSkill) {
+  const named = state.skills[skill.name];
+  return named?.cloudId === skill.id ? named : Object.values(state.skills).find(entry => entry.cloudId === skill.id);
+}
+
+export function nativeLocalReady(skill: CloudSkill, local?: LocalSkill): boolean {
+  return Boolean(local?.nativeFilesCurrent && local.folderHash === local.nativeBaseFolderHash
+    && local.cloudId === skill.id && local.nativeScope === skill.native_scope
+    && sameNativeReference(local.nativeReference, skill.native_reference));
+}
+
+/** A pre-native folder (no identity marker, no native state) the cloud now serves
+ * as a native Skill. It stays usable as before until its upgrade write lands. */
+export function pendingLegacyUpgrade(skill: CloudSkill, local: LocalSkill | undefined, state: NotisSyncState): boolean {
+  if (!isNativeSkill(skill) || !local || local.nativeReference || local.cloudId) return false;
+  const previous = previousNativeState(state, skill);
+  return Boolean(previous && !previous.nativeReference);
+}
+
+export function nativeLinkRows(response: SyncPullResponse, locals: LocalSkill[], state?: NotisSyncState): CloudSkill[] {
+  return response.skills.map(skill => {
+    const local = locals.find(row => row.name === skill.name);
+    return isNativeSkill(skill) && !nativeLocalReady(skill, local) && !(state && pendingLegacyUpgrade(skill, local, state))
+      ? { ...skill, status: 'disabled' } : skill;
+  });
+}
+
+export function retainMissingNativeState(previous: NotisSyncState, next: NotisSyncState): NotisSyncState {
+  const present = new Set(Object.values(next.skills).map(row => row.cloudId));
+  const retained = Object.fromEntries(Object.entries(previous.skills)
+    .filter(([, row]) => (row.nativeReference || row.nativeUnavailable) && !present.has(row.cloudId))
+    .map(([name, row]) => [name, { ...row, nativeUnavailable: true, verifiedAgentLinks: {} }]));
+  const history = structuredClone(previous.nativeHistory || {});
+  for (const [name, row] of [...Object.entries(previous.skills), ...Object.entries(next.skills)]) {
+    if (!row.nativeReference && !row.nativeUnavailable) continue;
+    const names = history[row.cloudId]?.names || [];
+    history[row.cloudId] = { names: [...new Set([...names, name])] };
+  }
+  return { ...next, skills: { ...retained, ...next.skills },
+    ...(Object.keys(history).length ? { nativeHistory: history } : {}) };
+}
+
+export function hasNativeFolderHistory(state: NotisSyncState, name: string): boolean {
+  return Object.values(state.nativeHistory || {}).some(row => row.names.includes(name));
+}