sshlg-skills 1.63.2 → 1.63.3

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## v1.63.3 — pinned sources for every Claude member; blocked members no longer stop the run
+
+- A Claude member whose installed bytes already equal the pin is now rebound to the hub's
+  pinned catalog: its marketplace source moves to the pin, with no install or uninstall, and
+  the run verifies that its install records did not change and its bytes still equal the pin.
+  A later native update therefore follows the pin, not upstream (B-191).
+- A member the native contract cannot change — installed only at project or local scope,
+  in user plus other scopes with different bytes, or a configured plugin — is reported as
+  blocked and keeps its installed version, while the other members and every later channel
+  (plain skills, runtime, hooks, Codex) proceed; the result is partial and exits nonzero.
+  Malformed install records still stop the whole run (B-192).
+- The hook runtime records which bytes the hub installed (`.managed.json`). A library module a
+  later package drops is moved to `.retired/<stamp>/` only while it still has those bytes, and
+  `update`/`hooks install` print what moved; hook scripts, edited, foreign or older unrecorded
+  files stay where they are (B-193).
+- Inserting into a non-empty object of a tab-indented JSON file keeps tabs (B-194).
+
 ## v1.63.2 — the Claude transaction keeps settings in Claude Code's format
 
 - Replacing a marketplace source in `~/.claude/settings.json` wrote the new object on one

package/bin/sshlg-skills.js

@@ -407,8 +407,9 @@ function withClaudePlan(steps, f) {
     steps.unshift(opres.step('claude-pins', 'home',
       'native immutable source transaction; protected catalogs/settings, scoped repair, rollback on failure, payload readback',
       { fingerprint: native.fingerprint, profile: native.profile,
-        members: native.jobs.map(j => `${j.pluginInstall}: ${j.action} @ ${j.row.commit}; ${j.row.files.length} files`)
-          .concat(native.equivalent.map(e => `${e.pluginInstall}: payload-equivalent, left installed (installed ${String(e.installed).slice(0, 7)}, pin ${e.pin.slice(0, 7)}; ${e.files} files equal)`)),
+        members: native.jobs.filter(j => j.action !== 'rebind').map(j => `${j.pluginInstall}: ${j.action} @ ${j.row.commit}; ${j.row.files.length} files`)
+          .concat(native.equivalent.map(e => `${e.pluginInstall}: payload-equivalent (installed ${String(e.installed).slice(0, 7)}, pin ${e.pin.slice(0, 7)}; ${e.files} files equal) — source rebind, no reinstall`))
+          .concat(native.blocked.map(b => `${b.pluginInstall}: blocked, left as installed — ${b.reason}`)),
         journal: path.join(native.transactionRoot, 'latest.json') }));
   }
   const result = attachWaitPlan(steps, f);
@@ -419,26 +420,31 @@ function runClaudePlan(planned, f) {
   const saved = claudePlans.get(planned);
   if (!saved) {
     log(`\n== Updating Claude Code plugins ==\n  skipped: ${claudeScope(f).skippedBy} (the Claude host is outside this run's scope)`);
-    return true;
+    return { ok: true, partial: false };
   }
-  for (const e of saved.native.equivalent) log(`    ${e.member || e.name}: payload equals pin ${e.pin.slice(0, 7)} (${e.files} files); installed source ${String(e.installed).slice(0, 7)} kept and its marketplace source is unchanged, so a later native update follows that source, not the pin`);
+  for (const e of saved.native.equivalent) log(`    ${e.member || e.name}: payload equals pin ${e.pin.slice(0, 7)} (${e.files} files); no reinstall — only its marketplace source moves to the pin catalog`);
+  for (const b of saved.native.blocked) log(`    ${b.name}: blocked, left as installed — ${b.reason}`);
+  const clean = !saved.native.blocked.length;
   if (!saved.native.jobs.length) {
     // Nothing is written; still describe the state at apply time, not at preview.
     let again;
     try { again = require('../lib/claude-pinned').prepare(SKILLS, saved.inventory, { home: os.homedir(), profileRoot: claudeRoot() }); }
-    catch (e) { log(`  Claude native transaction refused before execution: ${e.message}`); return false; }
-    if (again.fingerprint !== saved.native.fingerprint) { log('  Claude native state changed since the preview; run update again'); return false; }
-    log('  Claude native transaction: not needed — every member already carries its pinned payload');
-    return true;
+    catch (e) { log(`  Claude native transaction refused before execution: ${e.message}`); return { ok: false, partial: false }; }
+    if (again.fingerprint !== saved.native.fingerprint) { log('  Claude native state changed since the preview; run update again'); return { ok: false, partial: false }; }
+    log(clean ? '  Claude native transaction: not needed — every member already carries its pinned payload'
+      : '  Claude native transaction: nothing else to do; blocked members above keep their installed version (partial)');
+    return { ok: true, partial: !clean };
   }
   // Admission, version check and all backups happen before any other channel.
   let result;
   try { result = require('../lib/claude-pin-transaction').execute(saved.native, SKILLS, saved.inventory); }
-  catch(e) { log(`  Claude native transaction refused before execution: ${e.message}`); return false; }
+  catch(e) { log(`  Claude native transaction refused before execution: ${e.message}`); return { ok: false, partial: false }; }
   log(`  Claude native transaction: ${result.ok ? 'verified immutable payloads' : 'failed; inspect recovery receipt'} — ${result.receipt}`);
   for (const r of result.results) log(`    ${r.member}: ${r.status}${r.rollback ? '; rollback: ' + r.rollback : ''}`);
   if (result.error) log(`  ${result.error}`);
-  return result.ok;
+  if (!clean) log('  Claude: partial — blocked members above keep their installed version');
+  // A blocked member makes the result partial; the other channels still run.
+  return { ok: result.ok, partial: !clean };
 }
 
 /** The same contract for `update` — every subprocess, prune, router and runtime action. */
@@ -516,8 +522,9 @@ function renderDryRun(planned, mode) {
 function cmdInstall(f) {
   const planned = frozenOperations.get(f) || planInstall(f);
   if (f.dryRun) return renderDryRun(planned, 'install');
-  if (!runClaudePlan(planned, f)) return false;
-  let ok = true;
+  const claude = runClaudePlan(planned, f);
+  if (!claude.ok) return false;
+  let ok = !claude.partial;
   if (!f.claudeOnly) {
     const agents = skillsCliAgents(f);
     log(`\n== Installing to agents via skills CLI: ${agents.join(', ')} ==`);
@@ -590,8 +597,9 @@ function scopedRoutingTargets(f) {
 function cmdUpdate(f) {
   const planned = frozenOperations.get(f) || planUpdate(f);
   if (f.dryRun) return renderDryRun(planned, 'update');
-  if (!runClaudePlan(planned, f)) return false;
-  let ok = true;
+  const claude = runClaudePlan(planned, f);
+  if (!claude.ok) return false;
+  let ok = !claude.partial;
   // Count and execute the subprocess entries from the same frozen plan.
   progress.total =
     (!f.claudeOnly && fs.existsSync(path.join(ROOT, '.gitmodules')) ? 1 : 0)
@@ -659,6 +667,8 @@ function cmdUpdate(f) {
             + `${before.differing.length} changed`
           : '  already level with this package');
         for (const m of before.missing) log(`    + ${m}`);
+        if (r.retired && r.retired.length) log(`  retired ${r.retired.length} file(s) this package dropped (kept under ${root}/.retired/): ${r.retired.join(', ')}`);
+        if (r.ownedError) log(`  warning: ${r.ownedError}`);
       }
     } catch (e) {
       // Other update steps may finish, but failed runtime refresh makes the aggregate red.
@@ -3260,6 +3270,8 @@ function cmdHooks(argv) {
   function syncRuntime() {
     const result = require('../lib/runtime.js').sync(pkgRoot, root, { create: true });
     if (result.ok === false) throw new Error(result.reason);
+    if (result.retired && result.retired.length) log(`  runtime: retired ${result.retired.length} dropped file(s) to ${root}/.retired/: ${result.retired.join(', ')}`);
+    if (result.ownedError) log(`  runtime warning: ${result.ownedError}`);
     return root;
   }
 

package/lib/claude-pin-transaction.js

@@ -58,6 +58,12 @@ function verifyForeign(plan) {
 function verify(plan,job,row=job.row,files=row.files) {
   const registry=P.parseMetadata(fs.readFileSync(plan.registryFile,'utf8')).data;
   const records=registry.plugins?.[job.pluginInstall];
+  if(job.action==='rebind') {
+    // Only the marketplace source moved: install records stay exactly as planned and
+    // the installed bytes still equal the pin.
+    if(JSON.stringify(records)!==job.records) throw Error(job.name+': native install records changed during source rebind');
+    return S.verifyPayload(job.old.installPath,{files});
+  }
   if(!Array.isArray(records) || records.length!==1 || records[0].scope!=='user' || records[0].version!==row.version || records[0].gitCommitSha!==row.commit) throw Error(job.name+': native installed source readback differs from pin');
   const install=records[0].installPath;
   if(typeof install!=='string' || !require('./visibility-state').profilePath(install).startsWith(path.join(plan.profile,'plugins/cache')+path.sep)) throw Error('native installed root is outside expected cache');

package/lib/claude-pinned.js

@@ -62,7 +62,7 @@ function prepare(members,inventory,opts) {
   const transactionRoot=path.join(home,'.sshlg-skills/claude-pinned',Source.sha256(profile).slice(0,16),'transactions');
   const active=read(path.join(transactionRoot,'latest.json'),'null').data;
   if(fs.existsSync(path.join(transactionRoot,'lock')) || (active && (active.status==='running' || active.status==='failed' && (!active.settingsRestored || active.uncertain)))) throw Error('incomplete Claude transaction; inspect '+path.join(transactionRoot,'latest.json'));
-  const jobs=[],equivalent=[];
+  const jobs=[],equivalent=[],blocked=[];
   for(const row of rows) {
     const marketplace=row.pluginInstall.split('@')[1],dir=path.join(home,'.sshlg-skills/claude-pinned',Source.sha256(profile).slice(0,16),marketplace);
     const declaration=settings.data.extraKnownMarketplaces?.[marketplace];
@@ -73,17 +73,28 @@ function prepare(members,inventory,opts) {
     // (docs-only) source commit or extra project/local scopes need no native mutation,
     // and a reinstall would rewrite a payload directory live sessions are using.
     const user=Array.isArray(existing)?existing.filter(r=>r&&r.scope==='user'):[];
+    // B-191: such a member still gets the hub catalog and its marketplace source, so a
+    // later native update follows the pin; `rebind` never installs or uninstalls.
+    let rebind=null;
     if(user.length===1 && user[0].version===row.version && typeof user[0].installPath==='string'
         && !(existing.length===1 && user[0].gitCommitSha===row.commit)
         && Bindings.profilePath(user[0].installPath).startsWith(path.join(profile,'plugins/cache')+path.sep)
         && existing.every(r=>r && r.installPath===user[0].installPath && r.version===row.version)) {
       let equal=false;try {equal=Source.verifyPayload(user[0].installPath,row)>=1;}catch(_) {}
-      if(equal) {equivalent.push({name:row.name,pluginInstall:row.pluginInstall,version:row.version,pin:row.commit,installed:user[0].gitCommitSha||null,scopes:existing.length,files:row.files.length});continue;}
+      if(equal) {
+        equivalent.push({name:row.name,pluginInstall:row.pluginInstall,version:row.version,pin:row.commit,installed:user[0].gitCommitSha||null,scopes:existing.length,files:row.files.length});
+        rebind=user[0];
+      }
     }
-    if(existing!==undefined && (!Array.isArray(existing) || existing.length!==1 || existing[0]?.scope!=='user')) throw Error(row.name+': native immutable repair supports one user-scope install only');
+    if(!rebind && existing!==undefined && (!Array.isArray(existing) || !existing.length || existing.some(r=>!plain(r)) || existing.filter(r=>r.scope==='user').length>1)) throw Error(row.name+': malformed native install record');
+    // A supported operator configuration this contract cannot change blocks only its own
+    // member; the run continues for the others and reports partial.
+    const block=reason=>{blocked.push({name:row.name,pluginInstall:row.pluginInstall,reason});};
+    if(!rebind && existing!==undefined && (existing.length!==1 || existing[0].scope!=='user')) {block('native immutable repair supports one user-scope install only (installed scopes: '+existing.map(r=>r.scope).join(', ')+')');continue;}
     for(const id of Object.keys(registry.data.plugins)) if(id.endsWith('@'+marketplace) && id!==row.pluginInstall) throw Error(row.name+': marketplace has another installed plugin');
     let action='install',old=null,oldFiles=null,repairEligible=false;
-    if(existing) {
+    if(rebind) {action='rebind';old=rebind;}
+    else if(existing) {
       old=existing[0];
       if(typeof old.installPath!=='string' || !path.isAbsolute(old.installPath) || typeof old.version!=='string') throw Error(row.name+': invalid installed plugin metadata');
       const cacheRoot=path.join(profile,'plugins/cache')+path.sep;
@@ -97,9 +108,9 @@ function prepare(members,inventory,opts) {
       if(action==='reinstall' && !/^[a-f0-9]{40}$/.test(old.gitCommitSha||'')) throw Error(row.name+': repair requires prior immutable Git identity');
       if(action==='reinstall' && (oldFiles.length!==row.files.length || oldFiles.some(f=>!row.files.some(p=>p.path===f.path)))) throw Error(row.name+': unknown same-version payload files; preserve before repair');
       repairEligible=!(row.configSurface || configured(manifest.data) || oldFiles.some(f=>/\.(mcpb|dxt)$/i.test(f.path)) || Object.prototype.hasOwnProperty.call(settings.data.pluginConfigs||{},row.pluginInstall));
-      if(action==='reinstall' && !repairEligible) throw Error(row.name+': configured plugin repair is unsupported; options/data preserved');
+      if(action==='reinstall' && !repairEligible) {block('configured plugin repair is unsupported; options/data preserved');continue;}
     }
-    if(row.configSurface && action==='install') throw Error(row.name+': configured native install is outside the verified contract');
+    if(row.configSurface && action==='install') {block('configured native install is outside the verified contract');continue;}
     const file=path.join(dir,'.claude-plugin/marketplace.json'),catalog=JSON.stringify(Source.catalog(row),null,2)+'\n';
     // An existing hub-owned catalog must still belong to this exact member.
     if(!Bindings.profilePath(file).startsWith(home+path.sep)) throw Error(row.name+': managed catalog escapes home');
@@ -108,9 +119,9 @@ function prepare(members,inventory,opts) {
       const p=prior.data;
       if(!plain(p) || p.name!==marketplace || !Array.isArray(p.plugins) || p.plugins.length!==1 || p.plugins[0].name!==row.pluginInstall.split('@')[0] || p.plugins[0].source?.source!=='git-subdir' || p.plugins[0].source.url!=='https://github.com/'+row.repo+'.git') throw Error(row.name+': existing catalog is not owned by this member');
     }
-    jobs.push({name:row.name,pluginInstall:row.pluginInstall,marketplace,dir,file,catalog,action,row,old,oldFiles,repairEligible});
+    jobs.push({name:row.name,pluginInstall:row.pluginInstall,marketplace,dir,file,catalog,action,row,old,oldFiles,repairEligible,records:rebind?JSON.stringify(existing):null});
   }
-  const fingerprint=Source.sha256(JSON.stringify({equivalent,settings:settings.text,registry:registry.text,known:known.text,catalogs:jobs.map(j=>({text:read(j.file,'null').text,action:j.action,oldFiles:j.oldFiles})),inventory:rows,profile,home,bindings:[settingsFile,registryFile,knownFile,...jobs.map(j=>j.file)].map(Bindings.profilePath)}));
-  return {fingerprint,requested,profile,home,settingsFile,registryFile,knownFile,settings,registry,known,jobs,equivalent,transactionRoot};
+  const fingerprint=Source.sha256(JSON.stringify({equivalent,blocked,settings:settings.text,registry:registry.text,known:known.text,catalogs:jobs.map(j=>({text:read(j.file,'null').text,action:j.action,oldFiles:j.oldFiles})),inventory:rows,profile,home,bindings:[settingsFile,registryFile,knownFile,...jobs.map(j=>j.file)].map(Bindings.profilePath)}));
+  return {fingerprint,requested,profile,home,settingsFile,registryFile,knownFile,settings,registry,known,jobs,equivalent,blocked,transactionRoot};
 }
 module.exports={prepare,editAt,ownedSource,configured,parseMetadata};

package/lib/json-spans.js

@@ -80,7 +80,7 @@ function edit(text, object, key, value) {
   const multiline = /[\r\n]/.test(prefix);
   const indent = multiline ? prefix.slice(prefix.lastIndexOf('\n') + 1) : '';
   const colon = first ? text.slice(first.keyEnd, first.value.start) : ': ';
-  const encoded = multiline ? JSON.stringify(value, null, 2).replace(/\n/g, newline + indent) : JSON.stringify(value);
+  const encoded = multiline ? JSON.stringify(value, null, indent.includes('\t') ? '\t' : 2).replace(/\n/g, newline + indent) : JSON.stringify(value);
   const member = JSON.stringify(key) + colon + encoded;
   if (ps.length) return splice(ps[ps.length - 1].end, ps[ps.length - 1].end, ',' + (multiline ? newline + indent : '') + member);
   // Empty object has no foreign property bytes to alter. In a multi-line document an

package/lib/runtime.js

@@ -119,6 +119,49 @@ function managedFiles(pkgRoot) {
 const crypto = require('crypto');
 const JOURNAL = '.switch-journal.json';
 const PREVIOUS = '.prev-generation';
+const OWNED = '.managed.json';
+const RETIRED = '.retired';
+
+// B-193: the runtime records which bytes the hub itself installed. A later package
+// that drops a module retires it to `.retired/<stamp>/` only when the file still has
+// exactly those bytes; edited, foreign or unrecorded files stay. Never a deletion.
+function readOwned(root) {
+  try {
+    const d = JSON.parse(fs.readFileSync(path.join(root, OWNED), 'utf8'));
+    if (!d || d.version !== 1 || !d.files || typeof d.files !== 'object' || Array.isArray(d.files)) return null;
+    for (const p of Object.values(d.files)) if (!validPrint(p)) return null;
+    return d;
+  } catch (_) { return null; }
+}
+function settle(runtimeRoot, rels, result) {
+  try {
+    const retired = [], old = readOwned(runtimeRoot), keep = new Set(rels);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    for (const [rel, print] of Object.entries(old ? old.files : {})) {
+      // A hook script may still be wired in a host's settings: only library modules retire.
+      if (keep.has(rel) || !rel.startsWith('lib/')) continue;
+      let file, now;
+      try { file = managedPath(runtimeRoot, rel); now = fingerprint(file); } catch (_) { continue; }
+      if (!now || !same(now, print)) continue;
+      const dst = path.join(runtimeRoot, RETIRED, stamp, rel);
+      directory(path.join(runtimeRoot, RETIRED)); directory(path.join(runtimeRoot, RETIRED, stamp));
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      for (let d = path.dirname(dst); d !== path.join(runtimeRoot, RETIRED); d = path.dirname(d)) directory(d);
+      fs.renameSync(file, dst);
+      retired.push(rel);
+    }
+    const files = {};
+    for (const rel of rels) { const p = fingerprint(managedPath(runtimeRoot, rel)); if (p) files[rel] = p; }
+    const pending = path.join(runtimeRoot, `${OWNED}.${process.pid}.tmp`);
+    // Leftovers of a crashed writer (any pid) are ours to clear: we hold the runtime lock.
+    for (const n of fs.readdirSync(runtimeRoot)) if (n.startsWith(`${OWNED}.`) && n.endsWith('.tmp')) { try { fs.unlinkSync(path.join(runtimeRoot, n)); } catch (_) { /* gone */ } }
+    durable(pending, JSON.stringify({ version: 1, files }) + '\n');
+    fs.renameSync(pending, path.join(runtimeRoot, OWNED));
+    return { ...result, retired: retired.sort() };
+  } catch (e) {
+    return { ...result, retired: [], ownedError: `runtime ownership record not updated: ${e.message}` };
+  }
+}
 
 function stat(file) {
   try { return fs.lstatSync(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
@@ -250,7 +293,7 @@ function syncLocked(pkgRoot, runtimeRoot, exists) {
   if (!rels.length) return failure('package has no managed runtime files', 'not-needed');
   const rows = rels.map(rel => ({ rel, before: fingerprint(managedPath(runtimeRoot, rel)) }));
   if (exists && rows.every(row => same(row.before, fingerprint(managedPath(pkgRoot, row.rel))))) {
-    return { ok: true, status: 'unchanged', created: false, copied: [], reason: null };
+    return settle(runtimeRoot, rels, { ok: true, status: 'unchanged', created: false, copied: [], reason: null });
   }
   const staging = fs.mkdtempSync(path.join(runtimeRoot, '.staging-'));
   const prev = path.join(runtimeRoot, PREVIOUS);
@@ -298,7 +341,7 @@ function syncLocked(pkgRoot, runtimeRoot, exists) {
     fs.unlinkSync(journal);
     journaled = false;
     try { fs.rmSync(staging, { recursive: true, force: true }); } catch (_) { /* committed, inert staging */ }
-    return { ok: true, status: 'synced', created: !exists, copied: rels, reason: null };
+    return settle(runtimeRoot, rels, { ok: true, status: 'synced', created: !exists, copied: rels, reason: null });
   } catch (e) {
     if (journaled) {
       const rolled = recoverUnlocked(runtimeRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sshlg-skills",
-  "version": "1.63.2",
+  "version": "1.63.3",
   "skillsCli": "skills@1.7.2",
   "description": "The ssheleg harness skill layer: routing, delivery gates, specialist skills and durable handoffs for coding agents.",
   "bin": {