metergraph-cli 0.2.2 → 0.2.4

package/native/anchored-fs.c

@@ -0,0 +1,243 @@
+#define _DARWIN_C_SOURCE
+#define _GNU_SOURCE
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <errno.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <limits.h>
+#include <signal.h>
+
+/* Private, bounded pipe protocol. No paths or file contents are logged. All
+ * pathname lookups below the process root are relative to retained dirfds.
+ * This process has no network interface or arbitrary execution operation. */
+#define LIMIT (2 * 1024 * 1024)
+#define MAX_HANDLES 8192
+#define STAT_BYTES (11 * 8)
+/* Search permission is sufficient for *at traversal; acquiring a directory
+ * capability must not newly require directory-listing permission. */
+#if defined(O_SEARCH)
+#define DIRECTORY_ACCESS O_SEARCH
+#elif defined(O_PATH)
+#define DIRECTORY_ACCESS O_PATH
+#else
+#error "No search-only directory capability API on this target"
+#endif
+struct directory { int fd, parent; char *path, *name; dev_t dev; ino_t ino; };
+static struct directory dirs[MAX_HANDLES];
+static int ndirs = 0, rollback_mode = 0;
+struct entry { int parent; char *name; dev_t dev; ino_t ino; int owned; dev_t own_dev; ino_t own_ino; };
+static struct entry entries[MAX_HANDLES];
+static int nentries;
+static int files[MAX_HANDLES];
+static int nfiles;
+static int readall(int fd, void *data, size_t len) {
+  unsigned char *p=data;
+  while(len) { ssize_t n=read(fd,p,len); if(n<0 && errno==EINTR) continue; if(n<=0) return -1; p+=n; len-=n; } return 0;
+}
+static int writeall(int fd, const void *data, size_t len) {
+  const unsigned char *p=data;
+  while(len) { ssize_t n=write(fd,p,len); if(n<0 && errno==EINTR) continue; if(n<=0) return -1; p+=n; len-=n; } return 0;
+}
+static uint32_t get32(const unsigned char *p) { return (uint32_t)p[0]<<24 | (uint32_t)p[1]<<16 | (uint32_t)p[2]<<8 | p[3]; }
+static void put32(unsigned char *p,uint32_t n) { p[0]=n>>24;p[1]=n>>16;p[2]=n>>8;p[3]=n; }
+static void put64(unsigned char *p,uint64_t n) { for(int i=7;i>=0;i--) {p[i]=n&255;n>>=8;} }
+static int reply(int error,const void *data,uint32_t len) {
+  unsigned char h[8]; put32(h,error);put32(h+4,len);
+  return writeall(1,h,8) || (len && writeall(1,data,len));
+}
+static int basename_ok(const char *p) { return *p && strcmp(p,".") && strcmp(p,"..") && !strchr(p,'/'); }
+static int current(int idx) {
+  if(idx==0) return 1;
+  struct directory *d=&dirs[idx]; struct stat s;
+  if(!current(d->parent)) return 0;
+  if(fstatat(dirs[d->parent].fd,d->name,&s,AT_SYMLINK_NOFOLLOW)<0) return 0;
+  return S_ISDIR(s.st_mode) && s.st_dev==d->dev && s.st_ino==d->ino;
+}
+static int remember(int parent,const char *name,const struct stat *s);
+static int directory(const char *path) {
+  if(!path || path[0]!='/' || strlen(path)>=PATH_MAX) {errno=EINVAL;return -1;}
+  for(int i=0;i<ndirs;i++) if(dirs[i].fd>=0 && !strcmp(path,dirs[i].path)) return i;
+  if(!strcmp(path,"/")) return 0;
+  char *copy=strdup(path); if(!copy) return -1;
+  char *slash=strrchr(copy,'/'); char *name=strdup(slash+1);
+  if(!name || !basename_ok(name)) {free(copy);free(name);errno=EINVAL;return -1;}
+  if(slash==copy) slash[1]=0; else *slash=0;
+  int parent=directory(copy); free(copy);
+  if(parent<0) {free(name);return -1;}
+  int fd=openat(dirs[parent].fd,name,DIRECTORY_ACCESS|O_DIRECTORY|O_NOFOLLOW|O_CLOEXEC);
+  if(fd<0) {free(name);return -1;}
+  struct stat s;
+  if(fstat(fd,&s)<0 || !S_ISDIR(s.st_mode) || ndirs>=MAX_HANDLES) {close(fd);free(name);errno=EIO;return -1;}
+  /* A previous directory observation is a capability identity, not permission
+   * to adopt whatever object later occupies that spelling. */
+  for(int i=0;i<nentries;i++) if(entries[i].parent==parent && !strcmp(entries[i].name,name)) {
+    if(entries[i].dev!=s.st_dev || entries[i].ino!=s.st_ino) {close(fd);free(name);errno=ESTALE;return -1;}
+  }
+  int idx=ndirs++;
+  dirs[idx]=(struct directory){fd,parent,strdup(path),name,s.st_dev,s.st_ino};
+  remember(parent,name,&s);
+  return idx;
+}
+static int parent_for(const char *path,char **name) {
+  if(!path || path[0]!='/' || strlen(path)>=PATH_MAX) {errno=EINVAL;return -1;}
+  char *copy=strdup(path); if(!copy) return -1;
+  char *slash=strrchr(copy,'/'); *name=strdup(slash+1);
+  if(!*name || !basename_ok(*name)) {free(copy);free(*name);*name=NULL;errno=EINVAL;return -1;}
+  if(slash==copy) slash[1]=0; else *slash=0;
+  int parent=directory(copy);free(copy);return parent;
+}
+static int mutable_parent(int idx) { if(idx<0)return 0; if(!rollback_mode && !current(idx)) {errno=ESTALE;return 0;} return 1; }
+static int remember(int parent,const char *name,const struct stat *s) {
+  for(int i=0;i<nentries;i++) if(entries[i].parent==parent && !strcmp(entries[i].name,name)) {
+    entries[i].dev=s->st_dev;entries[i].ino=s->st_ino;return 0;
+  }
+  if(nentries>=MAX_HANDLES) {errno=EMFILE;return -1;}
+  entries[nentries++]=(struct entry){parent,strdup(name),s->st_dev,s->st_ino,0,0,0};return 0;
+}
+static int own(int parent,const char *name,const struct stat *s) {
+  if(remember(parent,name,s)<0)return -1;
+  for(int i=0;i<nentries;i++) if(entries[i].parent==parent && !strcmp(entries[i].name,name)) {entries[i].owned=1;entries[i].own_dev=s->st_dev;entries[i].own_ino=s->st_ino;return 0;}
+  errno=EIO;return -1;
+}
+static int promote(int parent,const char *name,const struct stat *s) {
+  if(remember(parent,name,s)<0)return -1;
+  for(int i=0;i<nentries;i++) if(entries[i].parent==parent && !strcmp(entries[i].name,name)) {entries[i].owned=0;return 0;}
+  errno=EIO;return -1;
+}
+static int expected(int parent,const char *name,int use_owned) {
+  for(int i=0;i<nentries;i++) if(entries[i].parent==parent && !strcmp(entries[i].name,name)) {
+    struct stat s; if(fstatat(dirs[parent].fd,name,&s,AT_SYMLINK_NOFOLLOW)<0)return -1;
+    dev_t dev=use_owned && entries[i].owned?entries[i].own_dev:entries[i].dev;
+    ino_t ino=use_owned && entries[i].owned?entries[i].own_ino:entries[i].ino;
+    if(s.st_dev!=dev || s.st_ino!=ino) {errno=ESTALE;return -1;}
+    return 0;
+  }
+  errno=ESTALE;return -1;
+}
+static void statbytes(unsigned char *out,const struct stat *s) {
+#if defined(__APPLE__)
+  struct timespec modified=s->st_mtimespec, changed=s->st_ctimespec;
+#else
+  struct timespec modified=s->st_mtim, changed=s->st_ctim;
+#endif
+  /* Keep seconds and nanoseconds separate. Multiplying time_t by 1e9 here
+   * would overflow for timestamps which JavaScript BigInt can represent. */
+  uint64_t fields[]={s->st_dev,s->st_ino,s->st_mode,s->st_nlink,s->st_uid,s->st_gid,s->st_size,
+    (uint64_t)modified.tv_sec,(uint64_t)modified.tv_nsec,(uint64_t)changed.tv_sec,(uint64_t)changed.tv_nsec};
+  for(int i=0;i<11;i++)put64(out+i*8,fields[i]);
+}
+static int filefd(const char *s) { char *end;long n=strtol(s,&end,10); if(*end || n<0 || n>=nfiles || files[n]<0) {errno=EBADF;return -1;}return files[n]; }
+int main(void) {
+  /* The JS owner defers termination until transaction cleanup completes.
+   * Group-delivered terminal signals must not revoke its live capabilities.
+   * Parent death closes stdin, so the loop exits without a signal handler. */
+  signal(SIGINT,SIG_IGN);signal(SIGTERM,SIG_IGN);signal(SIGHUP,SIG_IGN);
+  int root=open("/",DIRECTORY_ACCESS|O_DIRECTORY|O_CLOEXEC);struct stat rs;
+  if(root<0 || fstat(root,&rs)<0)return 1;
+  dirs[ndirs++]=(struct directory){root,-1,strdup("/"),strdup(""),rs.st_dev,rs.st_ino};
+  for(;;) {
+    unsigned char header[4]; if(readall(0,header,4))break;
+    uint32_t length=get32(header);if(length<2 || length>LIMIT) return 2;
+    unsigned char *request=malloc(length+1);if(!request)return 3;
+    if(readall(0,request,length)) {free(request);break;}request[length]=0;
+    int op=request[0],argc=request[1];char *args[8]={0};size_t pos=2;int malformed=argc>8;
+    for(int i=0;i<argc && !malformed;i++) {
+      if(pos+4>length) {malformed=1;break;}
+      uint32_t len=get32(request+pos);pos+=4;
+      if(pos+len>length || memchr(request+pos,0,len)) {malformed=1;break;}
+      args[i]=malloc(len+1);if(!args[i]) {malformed=1;break;}
+      memcpy(args[i],request+pos,len);args[i][len]=0;pos+=len;
+    }
+    int error=0; unsigned char out[STAT_BYTES];void *output=out;uint32_t outlen=0;
+    int parent=-1,fd=-1,result=-1;char *name=NULL;struct stat st;
+    errno=0;
+    if(malformed) error=EINVAL;
+    else switch(op) {
+      case 1: /* lstat: never follows the final entry */
+        if(argc!=1) {error=EINVAL;break;}
+        if(!strcmp(args[0],"/")) result=fstat(root,&st);
+        else {parent=parent_for(args[0],&name);if(parent<0)break;result=fstatat(dirs[parent].fd,name,&st,AT_SYMLINK_NOFOLLOW);}
+        if(!result) {
+          if(S_ISDIR(st.st_mode)) {
+            int pinned=directory(args[0]);struct stat opened;
+            if(pinned<0) {result=-1;break;}
+            if(fstat(dirs[pinned].fd,&opened)<0 || opened.st_dev!=st.st_dev || opened.st_ino!=st.st_ino) {errno=ESTALE;result=-1;break;}
+          }
+          statbytes(out,&st);outlen=STAT_BYTES;if(parent>=0 && !S_ISLNK(st.st_mode))remember(parent,name,&st);
+        }
+        break;
+      case 2: /* open: protocol flags are independent of host constants */
+        if(argc!=3) {error=EINVAL;break;}
+        parent=parent_for(args[0],&name);if(parent<0)break;
+        int kind=atoi(args[1]),flags=O_NOFOLLOW|O_CLOEXEC|O_NONBLOCK;
+        if(kind==0)flags|=O_RDONLY;else if(kind==1)flags|=O_RDWR;else if(kind==2)flags|=O_WRONLY|O_CREAT|O_EXCL;else {error=EINVAL;break;}
+        if(kind!=0 && !mutable_parent(parent))break;
+        fd=openat(dirs[parent].fd,name,flags,strtoul(args[2],NULL,10)&0777);
+        if(fd<0)break;
+        if(fstat(fd,&st)<0 || (!S_ISREG(st.st_mode) && !(kind==0 && S_ISDIR(st.st_mode))) || (S_ISREG(st.st_mode) && st.st_nlink!=1)) {close(fd);fd=-1;errno=ELOOP;break;}
+        if(nfiles>=MAX_HANDLES) {close(fd);errno=EMFILE;break;}
+        if((kind==2?own(parent,name,&st):remember(parent,name,&st))<0) {close(fd);break;}
+        put32(out,nfiles);outlen=4;files[nfiles++]=fd;result=0;break;
+      case 3: /* fstat */
+        if(argc!=1) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;result=fstat(fd,&st);if(!result){statbytes(out,&st);outlen=STAT_BYTES;}break;
+      case 4: /* bounded read from descriptor */
+        if(argc!=1) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;
+        if(fstat(fd,&st)<0)break;
+        if(!S_ISREG(st.st_mode) || st.st_size<0 || st.st_size>LIMIT) {errno=EFBIG;break;}
+        output=malloc(LIMIT+1);if(!output){errno=ENOMEM;break;}
+        size_t used=0;ssize_t got;
+        while(used<LIMIT && (got=read(fd,(char*)output+used,LIMIT-used))>0)used+=got;
+        if(got<0){break;}outlen=used;result=0;break;
+      case 5: /* write payload */
+        if(argc!=1) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;result=writeall(fd,request+pos,length-pos);break;
+      case 6:
+        if(argc!=2) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;result=fchmod(fd,strtoul(args[1],NULL,10)&0777);break;
+      case 7:
+        if(argc!=1) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;result=fsync(fd);break;
+      case 8:
+        if(argc!=1) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;result=close(fd);files[atoi(args[0])]=-1;break;
+      case 9: /* mkdir one basename */
+        if(argc!=2) {error=EINVAL;break;}parent=parent_for(args[0],&name);if(!mutable_parent(parent))break;
+        result=mkdirat(dirs[parent].fd,name,strtoul(args[1],NULL,10)&0777);
+        if(!result && !fstatat(dirs[parent].fd,name,&st,AT_SYMLINK_NOFOLLOW)) {own(parent,name,&st);}
+        break;
+      case 10: /* rename, anchored at both parents */
+        if(argc!=2) {error=EINVAL;break;}parent=parent_for(args[0],&name);if(!mutable_parent(parent) || expected(parent,name,1)<0)break;
+        char *destname=NULL;int dest=parent_for(args[1],&destname);
+        if(mutable_parent(dest)) {
+          if(!fstatat(dirs[dest].fd,destname,&st,AT_SYMLINK_NOFOLLOW) && (S_ISLNK(st.st_mode) || !S_ISREG(st.st_mode) || st.st_nlink!=1 || expected(dest,destname,0)<0)) {errno=ESTALE;}
+          else { result=renameat(dirs[parent].fd,name,dirs[dest].fd,destname);if(!result && !fstatat(dirs[dest].fd,destname,&st,AT_SYMLINK_NOFOLLOW))promote(dest,destname,&st); }
+        }free(destname);break;
+      case 11: case 12: /* unlink/rmdir only an object previously observed */
+        if(argc!=1) {error=EINVAL;break;}parent=parent_for(args[0],&name);if(!mutable_parent(parent) || expected(parent,name,1)<0)break;
+        result=unlinkat(dirs[parent].fd,name,op==12?AT_REMOVEDIR:0);
+        if(!result && op==12) for(int i=1;i<ndirs;i++) if(dirs[i].parent==parent && !strcmp(dirs[i].name,name) && dirs[i].fd>=0) {close(dirs[i].fd);dirs[i].fd=-1;}
+        break;
+      case 13: /* validate existing directory ancestry */
+        if(argc!=1) {error=EINVAL;break;}parent=directory(args[0]);if(parent<0)break;
+        if(current(parent))result=0;else errno=ESTALE;break;
+      case 15: /* exclusive hardlink promotion, never follows source */
+        if(argc!=2) {error=EINVAL;break;}parent=parent_for(args[0],&name);if(!mutable_parent(parent) || expected(parent,name,1)<0)break;
+        char *linkname=NULL;int linkparent=parent_for(args[1],&linkname);
+        if(mutable_parent(linkparent)) {result=linkat(dirs[parent].fd,name,dirs[linkparent].fd,linkname,0);if(!result && !fstatat(dirs[linkparent].fd,linkname,&st,AT_SYMLINK_NOFOLLOW))promote(linkparent,linkname,&st);}free(linkname);break;
+      case 16: /* positional bounded read */
+        if(argc!=3) {error=EINVAL;break;}fd=filefd(args[0]);if(fd<0)break;
+        size_t amount=strtoul(args[1],NULL,10);if(amount>LIMIT){error=EFBIG;break;}
+        output=malloc(amount?amount:1);if(!output){error=ENOMEM;break;}
+        ssize_t count=pread(fd,output,amount,strtoll(args[2],NULL,10));if(count>=0){outlen=count;result=0;}break;
+      case 14:
+        if(argc!=1 || (strcmp(args[0],"0") && strcmp(args[0],"1"))) {error=EINVAL;break;}rollback_mode=atoi(args[0]);result=0;break;
+      default:error=EINVAL;
+    }
+    if(!error && result<0)error=errno?errno:EIO;
+    if(reply(error,error?NULL:output,error?0:outlen))return 4;
+    if(output!=out)free(output);
+    free(name);for(int i=0;i<argc && i<8;i++)free(args[i]);free(request);
+  }
+  return 0;
+}

package/native/build.mjs

@@ -0,0 +1,55 @@
+// Development/release build only. Package consumers never run a compiler.
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TARGETS, DIGEST, REVISION, binaryFor, exactKeys, argumentsFor } from "./targets.mjs";
+const root = path.dirname(fileURLToPath(import.meta.url));
+const sha256 = bytes => createHash("sha256").update(bytes).digest("hex");
+function directory(dir) {
+  fs.mkdirSync(dir, {recursive:true});
+  if (!fs.lstatSync(dir).isDirectory() || fs.lstatSync(dir).isSymbolicLink()) throw new Error("unsafe build output");
+}
+export function build({output, revision, target = `${process.platform}-${process.arch}`} = {}) {
+  if (!TARGETS.includes(target) || target !== `${process.platform}-${process.arch}`) throw new Error("unsupported build host");
+  if (revision === undefined) {
+    revision = process.env.GITHUB_SHA;
+    if (revision === undefined) {
+      const git = spawnSync("git", ["rev-parse", "HEAD"], {cwd:root, encoding:"utf8"});
+      if (git.status !== 0) throw new Error("source revision unavailable");
+      revision = git.stdout.trim();
+    }
+  }
+  if (!REVISION.test(revision)) throw new Error("invalid source revision");
+  const provenanceOutput = output !== undefined;
+  output = path.resolve(output ?? root); directory(output); directory(path.join(output,"bin"));
+  const manifestPath = path.join(output,"manifest.json");
+  let artifacts = {};
+  if (fs.existsSync(manifestPath)) {
+    if (!fs.lstatSync(manifestPath).isFile() || fs.lstatSync(manifestPath).isSymbolicLink()) throw new Error("unsafe build manifest");
+    const previous = JSON.parse(fs.readFileSync(manifestPath,"utf8"));
+    if (!exactKeys(previous,["schema","artifacts"]) || previous.schema !== 1 || !exactKeys(previous.artifacts,Object.keys(previous.artifacts ?? {}))) throw new Error("invalid build manifest");
+    for (const [name,digest] of Object.entries(previous.artifacts)) {
+      if (!TARGETS.some(value=>binaryFor(value)===name) || !DIGEST.test(digest)) throw new Error("unknown build artifact");
+      const file=path.join(output,"bin",name);const stat=fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || sha256(fs.readFileSync(file)) !== digest) throw new Error("existing artifact integrity failed");
+      artifacts[name]=digest;
+    }
+  }
+  const name = binaryFor(target); const temporary = path.join(output,"bin",`.build-${randomBytes(12).toString("hex")}`);
+  try {
+    const result = spawnSync("clang", ["-std=c11", "-Wall", "-Wextra", "-Werror", "-O2", path.join(root,"anchored-fs.c"), "-o",temporary], {stdio:"inherit"});
+    if (result.status !== 0) throw new Error("native compilation failed");
+    fs.chmodSync(temporary,0o755);
+    const digest = sha256(fs.readFileSync(temporary)); fs.renameSync(temporary,path.join(output,"bin",name)); artifacts[name]=digest;
+    const ordered = Object.fromEntries(Object.entries(artifacts).sort(([a],[b])=>a.localeCompare(b)));
+    fs.writeFileSync(manifestPath,`${JSON.stringify({schema:1,artifacts:ordered},null,2)}\n`);
+    if (provenanceOutput) fs.writeFileSync(path.join(output,"provenance.json"),`${JSON.stringify({schema:1,source_revision:revision,source_sha256:sha256(fs.readFileSync(path.join(root,"anchored-fs.c"))),target,binary_sha256:digest},null,2)}\n`);
+    return {target,digest};
+  } finally {try {fs.unlinkSync(temporary);} catch(error) {if(error.code!=="ENOENT")throw error;} }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {const args=argumentsFor(process.argv.slice(2),[],["--output","--revision"]);build({output:args["--output"],revision:args["--revision"]});}
+  catch(error) {process.stderr.write(`${error.message}\n`);process.exitCode=1;}
+}

package/native/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schema": 1,
+  "artifacts": {
+    "anchored-fs-darwin-arm64": "787a6d122add60a261fc6c70717f270825af3be7512d7dea4104f608293370b6",
+    "anchored-fs-darwin-x64": "f569e48393b0650a93c8aaf2ef8984fd0dbf90e33f51d847db3c629a7c8fbd38",
+    "anchored-fs-linux-arm64": "6ac3eca79a8211a32dfd76eebeffe0b4b4e6d1540bacad739856b9c91094b308",
+    "anchored-fs-linux-x64": "401e2fd89ca15cd9d68c4e5077ca08a9caf0fe93434a0b243a361845b1284533"
+  }
+}

package/native/targets.mjs

@@ -0,0 +1,24 @@
+// Build and release allowlist. Presence here is not evidence of verification;
+// CI must execute the compiled helper on each declared host before assembly.
+export const TARGETS = Object.freeze(["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64"]);
+export const BINARY_PREFIX = "anchored-fs-";
+export const REVISION = /^[0-9a-f]{40}$/;
+export const DIGEST = /^[0-9a-f]{64}$/;
+export function binaryFor(target) {
+  if (!TARGETS.includes(target)) throw new Error("unsupported native target");
+  return `${BINARY_PREFIX}${target}`;
+}
+export function exactKeys(value, keys) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) &&
+    Object.keys(value).sort().join() === [...keys].sort().join();
+}
+export function argumentsFor(argv, required, optional = []) {
+  const allowed = new Set([...required, ...optional]); const result = {};
+  for (let i = 0; i < argv.length; i += 2) {
+    const name = argv[i]; const value = argv[i + 1];
+    if (!allowed.has(name) || Object.hasOwn(result, name) || typeof value !== "string" || value === "" || value.startsWith("--")) throw new Error("invalid build arguments");
+    result[name] = value;
+  }
+  if (required.some(name => !Object.hasOwn(result, name))) throw new Error("missing build arguments");
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {
@@ -12,6 +12,12 @@
   "files": [
     "bin/metergraph.js",
     "src/*.js",
+    "native/anchored-fs.c",
+    "native/build.mjs",
+    "native/targets.mjs",
+    "native/manifest.json",
+    "native/README.md",
+    "native/bin/*",
     "assets/skill/SKILL.md",
     "assets/skill/manifest.json",
     "assets/skills/manifest.json",
@@ -20,8 +26,9 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js",
-    "test:package": "node --test test/package/*.test.js"
+    "build:native": "node native/build.mjs",
+    "test": "node test/run-tests.js",
+    "test:package": "node test/run-tests.js package"
   },
   "engines": {
     "node": ">=22"

package/src/action-help.js

@@ -0,0 +1,130 @@
+// Human action help; command execution and JSON envelopes remain independent.
+const option = (name, value, summary) => ({ name, value, summary });
+const selectors = [
+  option("--model", "ID", "Model ID."),
+  option("--provider", "ID", "Provider; use instead of --channel."),
+  option("--channel", "ID", "Billing channel; use instead of --provider."),
+  option("--region", "ID", "Billing region."),
+];
+const pricingCommon = [
+  option("--url", "ORIGIN", "Service origin. Default: https://app.metergraph.dev."),
+  option("--timeout-ms", "N", "Request deadline, 100–30000 ms. Default: 10000."),
+  option("--api", "API", "public (default) or reference. Reference requires a loopback origin."),
+  option("--json", null, "Print JSON."),
+];
+const tokens = ["input", "output", "cache-read", "cache-write", "cache-write-5m", "cache-write-1h"].map(
+  name => option(`--${name}-tokens`, "N", name.startsWith("cache-write")
+    ? "Anthropic cache-write tokens."
+    : "Token count. Omitted counts stay unknown."));
+const pricing = {
+  models: ["Discover available models", "[--provider ID | --channel ID] [--limit N]", "metergraph pricing models --limit 10",
+    [...selectors, option("--limit", "N", "Models to show. Default: 20; max: 100.")],
+    "Current catalog. No account required."],
+  lookup: ["Look up a model's prices", "--model ID [--provider ID | --channel ID]", "metergraph pricing lookup --model gpt-5 --provider openai",
+    [...selectors, option("--at", "YYYY-MM-DD", "Price date (UTC). Default: now.")],
+    "Public catalog prices. No account required."],
+  calculate: ["Estimate cost from token counts", "--model ID [--input-tokens N] [--output-tokens N]", "metergraph pricing calculate --model gpt-5 --provider openai --input-tokens 1000 --output-tokens 200",
+    [...selectors, ...tokens, option("--batch", null, "Use batch rates."),
+      option("--at", "YYYY-MM-DD", "Price date (UTC). Default: now."),
+      option("--trace-format", "FORMAT", "Token format: anthropic.messages, openai.responses, openai.chat_completions or otel.gen_ai.")],
+    "Only supplied counts are sent. Partial costs are known subtotals. OpenAI cache reads cannot exceed total input. No model calls are made."],
+  market: ["Compare current rates on one billing channel", "--channel ID [--region ID] [--limit N]", "metergraph pricing market --channel openai-api --limit 10",
+    selectors.filter(o => ["--channel", "--region"].includes(o.name)).concat(option("--limit", "N", "Models to show. Default: 20; max: 100.")),
+    "Current prices, without historical or quality rankings. No account required."],
+  history: ["Inspect historical catalog prices", "--model ID --channel ID --api reference --url ORIGIN", "metergraph pricing history --model openai/gpt-5.6-terra --channel openai-api --api reference --url http://127.0.0.1:8765 --format chart",
+    selectors.filter(o => o.name !== "--provider").concat([
+      option("--api", "reference", "Required. History currently uses the local reference adapter."),
+      option("--at", "YYYY-MM-DD", "Reference lookup date at UTC midnight."),
+      option("--format", "FORMAT", "chart (default), table or html. Cannot combine with --json."),
+    ]), "Requires a loopback reference service. Historical data is not available from the public API."],
+};
+
+export function actionHelpData(topic, action, commands) {
+  if (topic === "pricing") {
+    const canonical = action === "cost" ? "calculate" : action;
+    const entry = pricing[canonical];
+    if (!entry) return null;
+    const [summary, usage, example, options, note] = entry;
+    const focused = options.map(o => {
+      if (o.name === "--model") return { ...o, summary: canonical === "models" ? "Filter by model ID." : "Required. Model ID." };
+      if (o.name === "--channel" && ["market", "history"].includes(canonical)) return { ...o, summary: "Required. Billing channel." };
+      if (o.name === "--region" && ["market", "history"].includes(canonical)) return { ...o, summary: "Billing region. Default: global." };
+      return o;
+    });
+    return { summary, usage: `metergraph pricing ${action} ${usage} [options]`,
+      options: [...focused, ...pricingCommon.filter(o => !options.some(specific => specific.name === o.name)
+        && !(o.name === "--api" && ["models", "calculate"].includes(action)))], examples: [example.replace("pricing calculate", `pricing ${action}`)], note };
+  }
+  if (topic === "experiments") {
+    const entry = commands.find(c => c.name === topic);
+    const names = { list: ["--workload", "--limit"], get: ["--id"],
+      estimate: ["--workload", "--treatment", "--last-n", "--sample-model", "--track"],
+      start: ["--workload", "--treatment", "--last-n", "--sample-model", "--track"] }[action];
+    if (!names) return null;
+    const specific = ["--workload", "--limit", "--id", "--treatment", "--last-n", "--sample-model", "--track"];
+    const options = entry.options.filter(o => !specific.includes(o.name) || names.includes(o.name)).map(o => {
+      if (o.name === "--agent-token-file") return { ...o, summary: action === "start"
+        ? "Private (0600) Debug key file with Allow analysis starts. Or set METERGRAPH_AGENT_TOKEN."
+        : "Private (0600) Metadata key file. Or use saved sign in or METERGRAPH_AGENT_TOKEN." };
+      const summaries = {
+        "--workload": action === "list" ? "Filter by workload ID." : "Required. Workload ID.",
+        "--id": "Required. Experiment ID.", "--limit": "Experiments to show. Default: 20; max: 50.",
+        "--treatment": "Required. PROVIDER/MODEL; repeat for up to 3 treatments.",
+        "--last-n": "Calls to replay. Default: 20; range: 10–40.",
+        "--sample-model": "Filter production calls by model.", "--track": "JSON path to compare; repeat up to 10 times.",
+      };
+      return { ...o, summary: summaries[o.name] ?? o.summary };
+    });
+    const invocation = { list: "[--workload ID] [--limit N]", get: "--id UUID",
+      estimate: "--workload ID --treatment PROVIDER/MODEL", start: "--workload ID --treatment PROVIDER/MODEL" }[action];
+    return { summary: { list: "List recent experiments", get: "Read an experiment's results",
+      estimate: "Estimate a model comparison before starting it", start: "Start a budgeted model comparison" }[action],
+      usage: `metergraph experiments ${action} ${invocation} [options]`, options,
+      examples: [`metergraph experiments ${action} ${{ list: "--limit 10", get: "--id UUID", estimate: "--workload ROUTE --treatment PROVIDER/MODEL", start: "--workload ROUTE --treatment PROVIDER/MODEL --agent-token-file /path/to/private-key" }[action]}`],
+      note: action === "start"
+        ? "Replays captured production prompts on the selected providers and incurs provider costs. Requires a Debug key with Allow analysis starts. Estimate first. Each start creates a new experiment; never retry a successful start."
+        : { list: "Uses Metadata access. Returns experiment summaries.",
+          get: "Uses Metadata access. Returns results without prompts or responses.",
+          estimate: "Uses Metadata access. Estimates provider cost without starting a replay." }[action] };
+  }
+  const entry = commands.find(c => c.name === `${topic} ${action}`);
+  if (!entry) return null;
+  const label = topic === "skill" ? "setup skill" : "workflow skills";
+  return { summary: action === "list" ? "List installed workflow skills"
+      : `${action === "install" ? "Install" : "Update"} the Metergraph ${label}`,
+    usage: `metergraph ${topic} ${action}${action === "list" ? "" : " --client codex|claude|cursor"} [options]`,
+    options: entry.options, examples: [`metergraph ${topic} ${action}${action === "list" ? "" : " --client codex"}`],
+    note: action === "list" ? "Lists installed workflow skills for all clients. Makes no changes."
+      : (action === "install" ? "Existing skills are left alone. No network requests." : "Replaces only unchanged skills owned by this CLI. No network requests.") };
+}
+
+// Connection details remain available offline without dominating everyday help.
+const ADVANCED_CONNECTION = new Set(["--url", "--config-dir", "--workspace", "--agent-token-file", "--timeout-ms", "--api"]);
+const SHORT_OPTIONS = {
+  "--project": "Project directory. Default: current directory.",
+  "--config-dir": "Credential directory. Default: per-user config directory.",
+  "--url": "Service origin. Default: project binding or hosted service.",
+  "--workspace": "Require this workspace ID.",
+  "--json": "Print JSON.",
+  "--client": "Agent: codex, claude or cursor.",
+  "--runtime": "local, cloud or cloud-no-shell. Inferred in a local terminal.",
+  "--skip-skill": "Skip agent skill installation.",
+  "--env-file": "Private env file. Default: .env.",
+  "--no-browser": "Print the approval link instead of opening it.",
+  "--signup": "Open sign up during browser approval.",
+  "--reconnect": "Allow switching the connected workspace.",
+  "--repair": "Approve replacement of a key that no longer verifies.",
+  "--deployment": "managed (default), customer-local, byoc or oss.",
+  "--confirm-prerequisites": "Confirm operator prerequisites are met.",
+  "--repository": "Repository identity as OWNER/NAME.",
+  "--no-repository": "Leave repository identity unset.",
+};
+export function displayOptions(options, topic, action, advanced = false) {
+  return options.filter(o => advanced || !ADVANCED_CONNECTION.has(o.name)
+    // History cannot run without these explicit connection selectors.
+    || (topic === "pricing" && action === "history" && ["--api", "--url"].includes(o.name)))
+    .map(o => ({ ...o, summary: advanced ? o.summary
+      : o.name === "--runtime" && ["skill", "skills"].includes(topic) ? "local (default) or cloud."
+      : o.name === "--url" && topic === "pricing" ? o.summary
+      : SHORT_OPTIONS[o.name] ?? o.summary }));
+}

package/src/agent-key.js

@@ -1,15 +1,17 @@
 import { verifyContext } from "./auth-oauth.js";
-import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE } from "./constants.js";
+import { DEFAULT_ORIGIN, MAX_BODY_BYTES } from "./constants.js";
 import { CREDENTIAL_MIN_LENGTH, readCredentialFile } from "./deployment-credential.js";
 import { checkDeployment } from "./doctor.js";
 import { AGENT_TOKEN_ENV, AGENT_URL_ENV } from "./environment.js";
 import { parseOrigin } from "./origin.js";
 import { send } from "./transport.js";
 
-// The read commands' second credential: a coding-agent key with Metadata
-// access that a person created on the Keys page and handed to the agent's
-// environment as a secret. It is for agents where browser sign in cannot
-// finish (SSH, cloud workspaces, CI, some containers).
+// The read commands' second credential: a coding-agent key that a person
+// created on the Keys page (or with a bundle's bin/agent-key) and handed to
+// the agent's environment as a secret. It has the Metadata role, or the
+// Debug role with workflow permissions. It is how agents read where browser
+// sign in cannot finish (SSH, cloud workspaces, CI, some containers), and how
+// they get the Debug role and permissions.
 //
 // The key comes only from the METERGRAPH_AGENT_TOKEN environment variable or
 // from a private file named by --agent-token-file (checked as setup checks
@@ -17,10 +19,11 @@ import { send } from "./transport.js";
 // written anywhere, never printed, and sent only as a bearer header to the
 // chosen origin, and only after that origin has answered the unauthenticated
 // deployment probe as a supported Metergraph service. Before any read, the
-// service's own workspace and capabilities documents must show exactly the
-// Metadata scope, no content access, the expected deployment profile and,
-// when one is pinned, the expected workspace. A broader key fails closed:
-// there is no fallback to Debug or Replay access.
+// service's own workspace and capabilities documents must show Metadata, or
+// Debug with workflow permissions, the expected deployment profile and, when
+// one is pinned, the expected workspace. A Replay key, or one with any other
+// scope, fails closed. The read commands send only Metadata requests,
+// whichever key they use.
 
 const TOKEN = new RegExp(`^[\\x21-\\x7e]{${CREDENTIAL_MIN_LENGTH},8192}$`);
 
@@ -66,6 +69,8 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
       ok: true,
       origin: binding.origin,
       workspaceId: binding.workspace_id,
+      // A slug or name to match against the verified workspace.
+      workspaceText: options.workspaceText ?? null,
       profile: binding.deployment_profile,
       originSource: "binding",
     };
@@ -74,6 +79,7 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
     ok: true,
     origin: requested ?? DEFAULT_ORIGIN,
     workspaceId: pinned,
+    workspaceText: options.workspaceText ?? null,
     profile: null,
     originSource: source ?? "default",
   };
@@ -84,7 +90,10 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
 //   { ok: false, outcome, reason }
 // verifiedProfile is the profile the caller already read from GET
 // /v1/deployment under the same deadline, or null to read it here.
-export async function keySession({ target, source, env, signal, verifiedProfile = null }) {
+// access is "read" for the read commands, or "experiment_start" for
+// experiments start, which needs Debug access and the start grant
+// (verifyContext).
+export async function keySession({ target, source, env, signal, verifiedProfile = null, access = "read" }) {
   // A key already in the environment is checked for shape before any
   // request; a key file is opened only once the origin has proven itself.
   let key = source.kind === "env" ? readAgentKey(source, env) : null;
@@ -108,7 +117,7 @@ export async function keySession({ target, source, env, signal, verifiedProfile
   const verified = await verifyContext(
     target.origin,
     token,
-    { profile, workspaceId: target.workspaceId, anyWorkspace: target.workspaceId === null },
+    { profile, workspaceId: target.workspaceId, anyWorkspace: target.workspaceId === null, access },
     signal,
   );
   if (!verified.ok) {
@@ -125,7 +134,8 @@ export async function keySession({ target, source, env, signal, verifiedProfile
       origin: target.origin,
       workspaceId: verified.workspaceId,
       profile,
-      scopes: [METADATA_SCOPE],
+      access: verified.access,
+      scopes: verified.scopes,
       accessToken: token,
     },
     documents: verified.documents,