@ssheleg/agent-stack 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## v0.16.1 — the installers refuse the shadow, and the pack stops mis-selling itself
+
+- **Both installers refuse to write plain copies over an installed plugin.** The family
+  audit of 2026-08-29 reproduced the shadow live: a bare `npx @ssheleg/telegram-dev`
+  created three plain copies in `~/.claude/skills/` while that plugin was enabled — and
+  this member had **no plugin check at all**, in either installer, so a bare
+  `npx @ssheleg/agent-stack` on a machine with the plugin would have shipped **four**
+  shadows, one per skill, each serving its frozen version forever. `bin/agent-stack.js`
+  and `install.sh` now implement make-skill v0.25.0's canon (`distribution.md`, "The
+  installer must refuse the shadow it documents"): detect from the TARGET home's
+  `installed_plugins.json` (keys are `<name>@<marketplace>`, and the two names differ
+  often), keep the `marketplaces/` dir read only as the fallback signal, refuse with
+  exit **3** and a remedy that names the spec read from the JSON
+  (`claude plugin marketplace update agent-stack` + `claude plugin update
+  agent-stack@<marketplace>`, plus the family launcher), offer `--force` as the recorded
+  deliberate override, fail open on a missing or corrupt JSON, and gate only the
+  `~/.claude` write — no other agent has plugins.
+- **`test/installer_test.js` joins `npm test` and CI** — 11 cases against throwaway
+  HOMEs: fresh / rerun-skip / `--force` / unknown-arg, plugin-present refusal (exit
+  code, remedy text, nothing written — all three asserted), a differently-named
+  marketplace in the remedy spec, corrupt JSON failing open, no false refusal on other
+  plugins or an `agent-stack-extra` prefix-collider, the marketplaces-dir fallback, and
+  the same matrix for `install.sh`. Watched failing before trusted: **7 of 11 red**
+  against the pre-fix installers (`git stash` the two, run, pop). The suite follows the
+  house residue rule — a failing case keeps its HOME, and the run ends by saying what it
+  left. It replaces the inline fresh-HOME-only step in `validate.yml`, which is the CI
+  shape that let the plugin-present case go unrun everywhere.
+- **A successful install now says how the next version arrives** — the last line names
+  `npx @ssheleg/agent-stack@latest --force` and the family launcher, in both installers.
+- **AST-01: the plugin stops selling itself as two skills.** `plugin.json` and
+  `marketplace.json` both opened with "Two skills: agent-orchestrator … and agent-evals"
+  while the pack ships **four** — `agent-interop` and `agent-harness` were invisible in
+  `claude plugin details` and on the marketplace. Both descriptions now name all four
+  skills with what each covers.
+
 ## v0.16.0 — the whole survey, not just its taxonomy
 
 v0.15.0 took the taxonomy and the named failure modes. This takes the rest: the write

package/bin/agent-stack.js

@@ -16,6 +16,44 @@ const os = require('os');
 
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/agent-stack';
+const PLUGIN = 'agent-stack';
+
+// Exit codes are the contract: 0 installed or skipped, 1 corrupted package,
+// 2 usage error, 3 refused — the plugin channel owns this agent (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
+ * or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory under-reports: a marketplace added
+ * from a local `directory` source has no dir there at all, and plugin names
+ * differ from marketplace names, so a check keyed on it stays green while the
+ * shadow lands. Absence and corruption both read as "no plugin": the fresh
+ * HOME is the common case, and an installer that crashes on a parse error
+ * refuses the machines that need it most.
+ */
+function installedPluginSpec(home, name) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed && typeof parsed === 'object' &&
+      parsed.plugins && typeof parsed.plugins === 'object'
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== 'object') return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === name) return `${name}@${name}`;
+      if (spec.startsWith(name + '@')) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
 
 function usage() {
   console.log(`agent-stack installer
@@ -25,6 +63,12 @@ Usage:
                                        into ~/.claude (skip existing unless --force)
   npx @ssheleg/agent-stack --help
 
+Exit codes:
+  0 installed or skipped   2 usage error
+  1 corrupted package      3 refused: the agent-stack PLUGIN is installed in
+                             this home — plain copies would shadow it (pass
+                             --force to write them anyway)
+
 Other install paths:
   Claude Code plugin:  /plugin marketplace add ${REPO}
                        /plugin install agent-stack@agent-stack
@@ -86,6 +130,41 @@ function main(argv) {
   }
 
   const home = os.homedir();
+
+  // One channel per agent. A plain ~/.claude/skills/<name> beside the installed
+  // agent-stack plugin is two listings of the same skill per skill this pack
+  // ships, and the stale copy wins — the exact shadow make-skill's distribution
+  // canon forbids (§ "The installer must refuse the shadow it documents").
+  // Refuse rather than create it, and refuse LOUDLY: a presence check keyed on
+  // the marketplaces/ dir alone that exits 0 is the fail-open class — a
+  // directory-sourced marketplace has no dir there, plugin names differ from
+  // marketplace names, and exit 0 reads as success to every script above it.
+  // Reproduced live 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped
+  // three shadows past exactly this hole while the plugin was enabled. Only the
+  // ~/.claude write is gated — no other agent has plugins.
+  const spec = installedPluginSpec(home, PLUGIN);
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', PLUGIN);
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+  if ((spec || viaMarketplaceDir) && !force) {
+    const found = spec
+      ? `installed as the Claude Code plugin ${spec}\n` +
+        '         (declared in ~/.claude/plugins/installed_plugins.json)'
+      : `registered as a Claude Code marketplace\n         (${marketplace})`;
+    console.error(
+      `refused: agent-stack is already ${found}.\n` +
+      `         Plain copies in ~/.claude/skills/ (${names.join(', ')})\n` +
+      '         would shadow the plugin and serve this frozen version forever.\n' +
+      '         Update the plugin channel instead:\n' +
+      '           claude plugin marketplace update agent-stack\n' +
+      `           claude plugin update ${spec || 'agent-stack@agent-stack'}\n` +
+      '         Family launcher (updates every member, prunes shadow copies):\n' +
+      '           npx --yes sshlg-skills@latest update\n' +
+      '         Pass --force to write the plain copies anyway — a deliberate choice\n' +
+      '         to run two channels, where the stale one wins.'
+    );
+    return EXIT_PLUGIN_PRESENT;
+  }
+
   for (const name of names) {
     installOne(
       `${name} skill`,
@@ -95,6 +174,15 @@ function main(argv) {
       force
     );
   }
+  // The last line says how the next version arrives — "Installed" is not a
+  // complete sentence. Auto-update is off on purpose: this member composes
+  // with its family, and per-marketplace autoUpdate moves each member on its
+  // own clock, into combinations nobody tested together.
+  console.log(
+    '\nUpdates: rerun `npx @ssheleg/agent-stack@latest --force`, or refresh the\n' +
+    'whole family with `npx --yes sshlg-skills@latest update` (every channel,\n' +
+    'and it prunes plain copies that would shadow a plugin).'
+  );
   return 0;
 }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && node test/installer_test.js"
   },
   "description": "Production patterns for AI agent orchestrators — tool-calling loops, multi-stage pipelines with checkpoints, LLM provider routing with fallback, four-layer memory with confidence decay — plus the wallet side of reselling LLM access. This package is the installer CLI.",
   "bin": {

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "agent-stack",
   "displayName": "Agent Stack",
-  "description": "Two skills: agent-orchestrator — tool-calling loops, multi-stage pipelines with checkpoints, provider routing with fallback, four-layer memory, context engineering, plus the wallet side of reselling LLM access; and agent-evals — run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.16.0",
+  "description": "Four skills: agent-orchestrator — tool-calling loops, pipelines with checkpoints, provider routing with fallback, memory architecture, plus the wallet side of reselling LLM access; agent-evals — run/trace/thread evals, LLM judges, and fixtures grown from production; agent-interop — MCP servers and clients, A2A agent cards, the MCP Registry, and gateways; agent-harness — system prompts, tool shaping, workflow-vs-agent, and auditing an agent system.",
+  "version": "0.16.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"