agentsys 5.9.1 → 5.11.0

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "agentsys",
   "description": "20 specialized plugins for AI workflow automation - task orchestration, PR workflow, slop detection, code review, drift detection, enhancement analysis, documentation sync, unified static analysis, perf investigations, topic research, agent config linting, cross-tool AI consultation, structured AI debate, workflow pattern learning, codebase onboarding, contributor guidance, and Zig language support",
-  "version": "5.9.1",
+  "version": "5.11.0",
   "owner": {
     "name": "Avi Fenesh",
     "url": "https://github.com/avifenesh"
@@ -26,10 +26,12 @@
       "name": "next-task",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/next-task.git"
+        "url": "https://github.com/agent-sh/next-task.git",
+        "ref": "v1.1.2",
+        "commit": "8feba0141a895d651a850cbe724a0e333c24a3a0"
       },
       "description": "Master workflow orchestrator: autonomous workflow with model optimization (opus/sonnet/haiku), two-file state management, workflow enforcement gates, 8 specialist agents",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/next-task"
     },
@@ -37,10 +39,12 @@
       "name": "prepare-delivery",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/prepare-delivery.git"
+        "url": "https://github.com/agent-sh/prepare-delivery.git",
+        "commit": "693d7649501608da49aea8efe610a7029100b8f2",
+        "ref": "v0.1.1"
       },
       "description": "Pre-ship quality gates: deslop, simplify, agnix, enhance, review loop, delivery validation, docs sync",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/prepare-delivery"
     },
@@ -48,7 +52,8 @@
       "name": "gate-and-ship",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/gate-and-ship.git"
+        "url": "https://github.com/agent-sh/gate-and-ship.git",
+        "commit": "bfff7063fde89a05ce480e37019bb6e00ba55984"
       },
       "description": "Quality gates then ship - chains /prepare-delivery then /ship in one command",
       "version": "0.1.0",
@@ -59,10 +64,12 @@
       "name": "ship",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/ship.git"
+        "url": "https://github.com/agent-sh/ship.git",
+        "commit": "189da6af2abdf67ab661098af2fc18453fe9e734",
+        "ref": "v1.1.2"
       },
       "description": "Complete PR workflow: commit to production, skips review when called from next-task, removes task from registry on cleanup, automatic rollback",
-      "version": "1.0.0",
+      "version": "1.1.2",
       "category": "deployment",
       "homepage": "https://github.com/agent-sh/ship"
     },
@@ -70,7 +77,8 @@
       "name": "deslop",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/deslop.git"
+        "url": "https://github.com/agent-sh/deslop.git",
+        "commit": "dc49a5309a104a011439f87b346d1c3b47375db2"
       },
       "description": "3-phase AI slop detection: regex patterns (HIGH), multi-pass analyzers (MEDIUM), CLI tools (LOW)",
       "version": "1.0.0",
@@ -81,10 +89,12 @@
       "name": "audit-project",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/audit-project.git"
+        "url": "https://github.com/agent-sh/audit-project.git",
+        "commit": "2c961a84ab5945670be44d6c54eb496099effe48",
+        "ref": "v1.0.1"
       },
       "description": "Multi-agent iterative code review until zero issues remain",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "category": "development",
       "homepage": "https://github.com/agent-sh/audit-project"
     },
@@ -92,7 +102,8 @@
       "name": "drift-detect",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/drift-detect.git"
+        "url": "https://github.com/agent-sh/drift-detect.git",
+        "commit": "e7edd602a0e24ae2bff8e262c58e481aae448944"
       },
       "description": "Deep repository analysis to realign project plans with code reality - detects drift, gaps, and creates prioritized reconstruction plans",
       "version": "1.0.0",
@@ -103,7 +114,8 @@
       "name": "enhance",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/enhance.git"
+        "url": "https://github.com/agent-sh/enhance.git",
+        "commit": "31e7d3861afb20b3d910be957387de23dc3ae854"
       },
       "description": "Master enhancement orchestrator: parallel analyzer execution for plugins, agents, docs, CLAUDE.md, and prompts with unified reporting",
       "version": "1.0.0",
@@ -114,7 +126,8 @@
       "name": "sync-docs",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/sync-docs.git"
+        "url": "https://github.com/agent-sh/sync-docs.git",
+        "commit": "961f5e67b583f70a4e0ad3ad83503ab90decc11d"
       },
       "description": "Standalone documentation sync: find outdated refs, update CHANGELOG, flag stale examples based on code changes",
       "version": "1.0.0",
@@ -125,7 +138,9 @@
       "name": "repo-intel",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/repo-intel.git"
+        "url": "https://github.com/agent-sh/repo-intel.git",
+        "ref": "v0.2.0",
+        "commit": "100dbff1969097af5e6a2ede7a2a79400aa0e60f"
       },
       "description": "Unified static analysis via agent-analyzer - git history, AST symbols, project metadata, and doc-code sync",
       "version": "0.2.0",
@@ -136,10 +151,12 @@
       "name": "perf",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/perf.git"
+        "url": "https://github.com/agent-sh/perf.git",
+        "commit": "189eb15e22bb6678da4d773f1c52b57d8880abff",
+        "ref": "v1.0.1"
       },
       "description": "Rigorous performance investigation workflow with baselines, profiling, hypotheses, and evidence-backed decisions",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "category": "development",
       "homepage": "https://github.com/agent-sh/perf"
     },
@@ -147,7 +164,8 @@
       "name": "learn",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/learn.git"
+        "url": "https://github.com/agent-sh/learn.git",
+        "commit": "e28ea11f4622509d1ae7425fa97f7dd719d43716"
       },
       "description": "Research topics online and create comprehensive learning guides with RAG-optimized indexes",
       "version": "1.0.0",
@@ -158,10 +176,12 @@
       "name": "agnix",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/agnix.git"
+        "url": "https://github.com/agent-sh/agnix.git",
+        "commit": "e0d9ce8106830f7db9cadb5359259536f6239e2f",
+        "ref": "v0.22.1"
       },
       "description": "Lint agent configuration files (SKILL.md, CLAUDE.md, hooks, MCP) against 414 rules across 10+ AI tools",
-      "version": "1.1.0",
+      "version": "0.22.1",
       "category": "development",
       "homepage": "https://github.com/agent-sh/agnix"
     },
@@ -169,7 +189,8 @@
       "name": "consult",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/consult.git"
+        "url": "https://github.com/agent-sh/consult.git",
+        "commit": "3115688a7c6079a04e8caa0183c1ca020e3d413d"
       },
       "description": "Cross-tool AI consultation: get second opinions from Gemini CLI, Codex CLI, Claude Code, OpenCode, or Copilot CLI with model and thinking effort control",
       "version": "1.0.0",
@@ -180,10 +201,12 @@
       "name": "debate",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/debate.git"
+        "url": "https://github.com/agent-sh/debate.git",
+        "commit": "aba659706bd25f7e394096acb457446e44966711",
+        "ref": "v1.0.1"
       },
       "description": "Structured multi-round debate between AI tools with proposer/challenger roles and verdict",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/debate"
     },
@@ -191,10 +214,12 @@
       "name": "web-ctl",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/web-ctl.git"
+        "url": "https://github.com/agent-sh/web-ctl.git",
+        "commit": "345e44bc8a7b373728afce6c0d94ef067b5abc82",
+        "ref": "v1.1.0"
       },
       "description": "Browser automation and web testing toolkit for AI agents - headless browser control, persistent sessions, auth handoff, and prompt injection defense",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "category": "automation",
       "homepage": "https://github.com/agent-sh/web-ctl"
     },
@@ -202,10 +227,12 @@
       "name": "skillers",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/skillers.git"
+        "url": "https://github.com/agent-sh/skillers.git",
+        "commit": "e1c1a9b752c0d20a0a1f83747c26e5dea195b5ae",
+        "ref": "v0.2.1"
       },
       "description": "Learn from workflow patterns across sessions and suggest skills, hooks, and agents to automate repetitive work",
-      "version": "1.0.0",
+      "version": "0.2.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/skillers"
     },
@@ -213,10 +240,12 @@
       "name": "onboard",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/onboard.git"
+        "url": "https://github.com/agent-sh/onboard.git",
+        "ref": "v0.1.1",
+        "commit": "6c2e47e567aac6249a0df6d15491cbcd42ce7717"
       },
       "description": "Codebase onboarding - automated data collection and interactive project orientation",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/onboard"
     },
@@ -224,10 +253,12 @@
       "name": "can-i-help",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/can-i-help.git"
+        "url": "https://github.com/agent-sh/can-i-help.git",
+        "ref": "v0.1.1",
+        "commit": "f1364158deb359b581d7113a54e8a6aa7a6d8679"
       },
       "description": "Find where to contribute to any project - matches developer skills to test gaps, stale docs, bugspots, and open issues",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/can-i-help"
     },
@@ -235,7 +266,8 @@
       "name": "zig-lsp",
       "source": {
         "source": "url",
-        "url": "https://github.com/agent-sh/zig-lsp.git"
+        "url": "https://github.com/agent-sh/zig-lsp.git",
+        "commit": "ecf32677d7bb3cc8e28112bb3c70dd7809a3aea7"
       },
       "description": "Zig language server for Claude Code via ZLS - automatic diagnostics after every edit, jump-to-definition, find-references, and hover. Requires zls in PATH",
       "version": "0.1.0",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.9.1",
+  "version": "5.11.0",
   "description": "Professional-grade slash commands for Claude Code with cross-platform support",
   "keywords": [
     "workflow",

package/CHANGELOG.md

@@ -9,6 +9,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.11.0] - 2026-04-26
+
+### Changed
+- **Upgraded marketplace sub-plugin pins from SHA-only to tag+SHA** after each downstream plugin cut security releases. Post-run totals: 12 pinned to tags, 8 fell back to default-branch SHA (up from 7/13 in v5.10.0). New tag pins in this wave: `prepare-delivery` v0.1.1, `audit-project` v1.0.1, `next-task` v1.1.2, `ship` v1.1.2, `skillers` v0.2.1, `onboard` v0.1.1, `can-i-help` v0.1.1, `perf` v1.0.1, `debate` v1.0.1. Consumers now install from verifiable release tags for these plugins.
+
+### Propagated upstream security fixes
+- agent-core v0.4.4 synced into all 13 consumers via `lib/`: fixer.js symlink + TOCTOU guards (#14 agent-core), earlier v0.4.3 code-point-safe truncate + sync-workflow test-file exclusion, v0.4.2 additive sync + upstreamed workflow-state/queries, v0.4.1 binary SHA-256 + zip-slip defenses.
+- prepare-delivery + audit-project: falsePositive review-bypass cap (50% ratio + required reason).
+- next-task: worktree-manager TASK_ID/BASE_BRANCH validation.
+- ship: platform-API health checks instead of log-grep rollback DoS.
+- skillers: transcript redaction pipeline (ported from consult).
+- onboard + can-i-help: explicit argv arrays in collector git invocations.
+- perf: command-parser error message accuracy.
+- debate: SKILL.md routes AI CLI invocations through consult's hardened ACP transport.
+
+## [5.10.0] - 2026-04-26
+
+### Security
+- **Marketplace supply-chain hardening** (#347) - pin every `source: "url"` sub-plugin entry in `.claude-plugin/marketplace.json` to an immutable commit SHA (plus release tag when one exists) instead of tracking default branches. Unpinned `source: "url"` entries previously let `claude plugin install` follow the remote's default branch, meaning any sub-plugin compromise would ship code to every user on their next install. New `scripts/pin-marketplace.js` resolves `v<version>` tags to commit SHAs via `gh api repos/.../git/ref/tags/<tag>` (annotated tags are dereferenced to the underlying commit), rejects ambiguous array responses, and falls back to default-branch HEAD SHA when the desired tag does not yet exist. Covered by `__tests__/pin-marketplace.test.js`.
+- **Reusable CI workflow SHA-pinned** (#347) - `agent-sh/.github/.github/workflows/agnix.yml@main` pinned to an explicit commit SHA so a compromise of the shared workflows repo cannot silently change agentsys's CI behavior.
+- **Release workflow shell injection hardening** (#347) - replaced 5 shell blocks that interpolated `${{ inputs.version }}` / `${{ github.event.inputs.* }}` directly into bash with `env:` block wiring; values are now read as shell variables so a malicious tag/input cannot break out of the command string.
+- **Removed self-referential npm dependency** (#347) - the `"agentsys": "^5.0.0"` entry in `package.json` / `package-lock.json` had no functional purpose and could confuse resolvers.
+- **`agent-analyzer` binary downloader security** (#350, synced from agent-core) - `lib/binary/index.js` now requires a matching `.sha256` sidecar, computes and verifies SHA-256 before extraction (with an explicit `skipChecksum` escape hatch for local dev), and extracts into an isolated scratch directory with archive-path-traversal defenses: reject absolute paths, UNC paths, drive letters, `..` segments, and symlinks; copy only the expected binary into the final install location; scrub the scratch tree afterward. Windows extraction moved from `Expand-Archive` command strings to a `-File` PowerShell script with env-var argument passing so paths containing spaces are handled safely. Covered by `lib/binary/index.test.js`.
+
+### Changed
+- **Marketplace pins upgraded to release tags** - post-#347, re-ran `scripts/pin-marketplace.js` after the downstream plugins cut tagged releases:
+  - `agnix`: default-branch SHA -> `v0.22.1` (tag + commit)
+  - `web-ctl`: default-branch SHA -> `v1.1.0` (tag + commit)
+  - `ship`: default-branch SHA -> `v1.1.1` (tag + commit)
+  - Running totals: 7 plugins pinned to tag + SHA, 13 still on default-branch SHA pending their first release tag.
+- Bumped `version` fields in `marketplace.json` for `agnix`, `web-ctl`, and `ship` to match the latest published tags so future `pin-marketplace.js` runs resolve to the correct refs.
+
 ## [5.9.1] - 2026-04-26
 
 ### Changed

package/bin/cli.js

@@ -342,6 +342,15 @@ function resolvePluginDeps(names, marketplace) {
  * @param {string} version - Expected version string
  * @returns {Promise<string>} Path to extracted plugin directory
  */
+// TODO(agentsys-security): this local dev installer currently honors only
+// `source.url` + `plugin.version` and ignores `source.ref` / `source.commit`
+// from marketplace.json. Claude Code's plugin installer (the primary install
+// path for end users) DOES honor `ref` and `commit` per the marketplace
+// schema, so the pins added by scripts/pin-marketplace.js are authoritative
+// for real users. This dev CLI should be updated to prefer `source.commit`
+// (then `source.ref`, then `plugin.version`) when resolving the fetch ref,
+// so local dev gets the same supply-chain guarantees as production installs.
+// Tracked as a follow-up; not fixed in PR #347 to keep that PR scoped.
 async function fetchPlugin(name, source, version) {
   const cacheDir = getPluginCacheDir();
   const pluginDir = path.join(cacheDir, name);

package/lib/binary/index.js

@@ -6,6 +6,19 @@
  * Handles lazy downloading and execution. Since Claude Code plugins have no
  * postinstall hooks, the binary is downloaded at runtime on first use.
  *
+ * Security hardening (2026-04-26 audit):
+ *   - Every release asset is verified against its `<asset>.sha256` sidecar
+ *     before extraction. A mismatch aborts with a clear message.
+ *   - Archives are extracted into an isolated tmpdir. Each entry path is
+ *     validated to reject absolute paths, Windows drive letters, and parent
+ *     traversal (`..`). The expected binary is then moved to the final
+ *     destination; everything else is discarded.
+ *   - The Windows zip path runs a PowerShell helper script via `-File` and
+ *     passes paths through environment variables, so PowerShell never
+ *     re-parses a command string (which broke on spaces/brackets). The
+ *     script validates every zip entry before extracting it and rejects
+ *     absolute, UNC, and parent-traversal entries.
+ *
  * @module lib/binary
  */
 
@@ -14,6 +27,7 @@ const path = require('path');
 const os = require('os');
 const https = require('https');
 const cp = require('child_process');
+const crypto = require('crypto');
 const { promisify } = require('util');
 
 const execFileAsync = promisify(cp.execFile);
@@ -120,7 +134,7 @@ async function isAvailableAsync() {
 }
 
 // ---------------------------------------------------------------------------
-// Download
+// Download + checksum verification
 // ---------------------------------------------------------------------------
 
 /**
@@ -180,67 +194,400 @@ function downloadToBuffer(url) {
 }
 
 /**
- * Extract a tar.gz buffer into a directory using the system tar command.
+ * Parse the leading 64-hex digest from a `.sha256` sidecar body.
+ * Tolerant of these formats (GNU coreutils + BSD `shasum`):
+ *   "<64-hex>\n"
+ *   "<64-hex>  <filename>\n"        (text mode, two-space separator)
+ *   "<64-hex>  *<filename>\n"       (binary mode, leading asterisk)
+ *   "<64-hex> <filename>\n"         (single-space variants)
+ * Throws if no valid digest is found.
+ * @param {string} body
+ * @returns {string} lower-cased 64-char hex digest
+ */
+function parseSha256Sidecar(body) {
+  if (typeof body !== 'string') body = String(body || '');
+  const match = body.trim().match(/^([A-Fa-f0-9]{64})\b/);
+  if (!match) {
+    throw new Error('Could not parse SHA-256 digest from sidecar body');
+  }
+  return match[1].toLowerCase();
+}
+
+/**
+ * Fetch and parse a `.sha256` sidecar next to an asset URL.
+ * @param {string} assetUrl full URL of the archive (not the sidecar)
+ * @returns {Promise<string>} lower-cased hex digest
+ */
+async function downloadSha256(assetUrl) {
+  const sidecarUrl = assetUrl + '.sha256';
+  const buf = await downloadToBuffer(sidecarUrl);
+  return parseSha256Sidecar(buf.toString('utf8'));
+}
+
+/**
+ * Compute the lower-case hex SHA-256 of a Buffer.
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Verify a downloaded buffer against an expected hex digest.
+ * Throws with a security-focused message on mismatch.
  * @param {Buffer} buf
- * @param {string} destDir
- * @returns {Promise<void>}
+ * @param {string} expectedHex
+ * @param {string} filename user-facing name for the error message
  */
-function extractTarGz(buf, destDir) {
+function verifySha256(buf, expectedHex, filename) {
+  const expected = String(expectedHex || '').toLowerCase();
+  const actual = sha256Hex(buf);
+  if (expected !== actual) {
+    throw new Error(
+      'SHA-256 verification failed for ' + filename + ': ' +
+      'expected ' + expected + ', got ' + actual + '. ' +
+      'This could indicate a tampered release. Do not extract.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Archive entry validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Reject archive entries with paths that could escape the extract directory.
+ * Rules:
+ *   - No absolute POSIX paths (leading `/`)
+ *   - No Windows absolute paths (drive letter like `C:\` or `C:/`)
+ *   - No UNC paths (`\\server\share`)
+ *   - No `..` as a path component
+ *   - No empty entry names
+ * @param {string} entry
+ * @throws {Error} on unsafe entry
+ */
+function assertSafeArchiveEntry(entry) {
+  if (!entry || typeof entry !== 'string') {
+    throw new Error('Refusing to extract archive with empty entry name');
+  }
+  const name = entry.replace(/\\/g, '/').trim();
+  if (name.length === 0) {
+    throw new Error('Refusing to extract archive with empty entry name');
+  }
+  if (name.startsWith('//')) {
+    throw new Error('Refusing to extract archive with UNC entry: ' + entry);
+  }
+  if (name.startsWith('/')) {
+    throw new Error('Refusing to extract archive with absolute entry: ' + entry);
+  }
+  if (/^[A-Za-z]:[\\/]/.test(entry)) {
+    throw new Error('Refusing to extract archive with Windows absolute entry: ' + entry);
+  }
+  const parts = name.split('/').filter(function(p) { return p.length > 0; });
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '..') {
+      throw new Error('Refusing to extract archive with parent-traversal entry: ' + entry);
+    }
+  }
+}
+
+/**
+ * List the entries inside a tar.gz buffer by running `tar -tz` over stdin.
+ * Returns the raw list; caller is responsible for validating each entry.
+ * @param {Buffer} buf
+ * @returns {Promise<string[]>}
+ */
+function listTarGzEntries(buf) {
   return new Promise(function(resolve, reject) {
-    const tarDest = process.platform === 'win32' ? destDir.replace(/\\/g, '/') : destDir;
-    const tar = cp.spawn('tar', ['xz', '-C', tarDest], {
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
+    const tar = cp.spawn('tar', ['-tz'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
     let stderr = '';
+    tar.stdout.on('data', function(d) { stdout += d; });
     tar.stderr.on('data', function(d) { stderr += d; });
-    tar.stdin.write(buf);
-    tar.stdin.end();
+    tar.on('error', reject);
     tar.on('close', function(code) {
       if (code !== 0) {
-        reject(new Error('tar extraction failed (code ' + code + '): ' + stderr));
-      } else {
-        resolve();
+        reject(new Error('tar -tz listing failed (code ' + code + '): ' + stderr));
+        return;
       }
+      const entries = stdout.split(/\r?\n/).filter(function(l) { return l.length > 0; });
+      resolve(entries);
     });
-    tar.on('error', reject);
+    tar.stdin.write(buf);
+    tar.stdin.end();
   });
 }
 
 /**
- * Extract a zip buffer into a directory using PowerShell Expand-Archive (Windows).
+ * Verify that a path resolved from extraction lies inside a known root.
+ * Guards against symlinks and any surprise introduced by the OS extractor.
+ * @param {string} root
+ * @param {string} candidate
+ */
+function assertInsideRoot(root, candidate) {
+  const rootResolved = path.resolve(root) + path.sep;
+  const candResolved = path.resolve(candidate);
+  if (candResolved !== path.resolve(root) && !candResolved.startsWith(rootResolved)) {
+    throw new Error('Extracted path escapes extract root: ' + candidate);
+  }
+}
+
+/**
+ * Recursively walk a directory and return all file paths (not dirs).
+ * Throws if any symlink is encountered (defense in depth: no surprise escapes).
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkFiles(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    const st = fs.lstatSync(cur);
+    if (st.isSymbolicLink()) {
+      throw new Error('Refusing to follow symlink produced by extractor: ' + cur);
+    }
+    if (st.isDirectory()) {
+      const names = fs.readdirSync(cur);
+      for (let i = 0; i < names.length; i++) {
+        stack.push(path.join(cur, names[i]));
+      }
+    } else if (st.isFile()) {
+      out.push(cur);
+    }
+  }
+  return out;
+}
+
+/**
+ * Remove a directory tree, tolerating already-missing paths.
+ * @param {string} dir
+ */
+function rmrf(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (e) {
+    /* ignore */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a tar.gz buffer into a scratch directory, validating entries first.
+ * Returns the scratch directory; caller is responsible for moving files out
+ * and calling rmrf() on it.
  * @param {Buffer} buf
- * @param {string} destDir
- * @param {string} binaryName
- * @returns {Promise<void>}
+ * @returns {Promise<string>} scratch dir
  */
-function extractZip(buf, destDir, binaryName) {
-  return new Promise(function(resolve, reject) {
-    const tmpZip = path.join(os.tmpdir(), binaryName + '-' + Date.now() + '.zip');
-    fs.writeFileSync(tmpZip, buf);
-    const cmd = 'Expand-Archive -Path \'' + tmpZip + '\' -DestinationPath \'' + destDir + '\' -Force';
-    const ps = cp.spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', cmd], {
-      stdio: ['ignore', 'pipe', 'pipe']
+async function extractTarGzToScratch(buf) {
+  const entries = await listTarGzEntries(buf);
+  for (let i = 0; i < entries.length; i++) {
+    assertSafeArchiveEntry(entries[i]);
+  }
+
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-analyzer-tar-'));
+
+  try {
+    await new Promise(function(resolve, reject) {
+      const tar = cp.spawn('tar', ['xz', '-C', scratch], { stdio: ['pipe', 'pipe', 'pipe'] });
+      let stderr = '';
+      tar.stderr.on('data', function(d) { stderr += d; });
+      tar.on('error', reject);
+      tar.on('close', function(code) {
+        if (code !== 0) {
+          reject(new Error('tar extraction failed (code ' + code + '): ' + stderr));
+        } else {
+          resolve();
+        }
+      });
+      tar.stdin.write(buf);
+      tar.stdin.end();
     });
-    let stderr = '';
-    ps.stderr.on('data', function(d) { stderr += d; });
-    ps.on('close', function(code) {
-      try { fs.unlinkSync(tmpZip); } catch (e) { /* ignore */ }
-      if (code !== 0) {
-        reject(new Error('zip extraction failed (code ' + code + '): ' + stderr));
-      } else {
-        resolve();
-      }
+
+    // Defense in depth: reject any symlink or non-regular entry the OS
+    // extractor may have created, and confirm every file resolves inside
+    // scratch.
+    const files = walkFiles(scratch);
+    for (let i = 0; i < files.length; i++) {
+      assertInsideRoot(scratch, files[i]);
+    }
+  } catch (err) {
+    rmrf(scratch);
+    throw err;
+  }
+
+  return scratch;
+}
+
+/**
+ * PowerShell script body that validates and extracts a zip entry-by-entry
+ * using .NET's System.IO.Compression.ZipFile. Paths and output dir are read
+ * from environment variables (`SRC_ZIP`, `DEST_DIR`) so no argument parsing
+ * can split on spaces, wildcards, or quotes.
+ *
+ * Rejects:
+ *   - Absolute entry names (POSIX `/`, Windows `C:\`)
+ *   - UNC entry names (`\\server\share`)
+ *   - Any `..` path component
+ *   - Resolved paths that escape the destination directory
+ *
+ * On any validation failure the script writes to stderr and exits with a
+ * non-zero status; nothing is extracted.
+ */
+const EXTRACT_ZIP_PS1 = [
+  '$ErrorActionPreference = "Stop"',
+  '$src  = $env:SRC_ZIP',
+  '$dest = $env:DEST_DIR',
+  'if ([string]::IsNullOrEmpty($src) -or [string]::IsNullOrEmpty($dest)) {',
+  '  [Console]::Error.WriteLine("SRC_ZIP and DEST_DIR must both be set"); exit 2',
+  '}',
+  'Add-Type -AssemblyName System.IO.Compression.FileSystem',
+  '$destFull = [System.IO.Path]::GetFullPath($dest)',
+  'if (-not $destFull.EndsWith([System.IO.Path]::DirectorySeparatorChar)) {',
+  '  $destFull = $destFull + [System.IO.Path]::DirectorySeparatorChar',
+  '}',
+  '$zip = [System.IO.Compression.ZipFile]::OpenRead($src)',
+  'try {',
+  '  foreach ($entry in $zip.Entries) {',
+  '    $name = $entry.FullName',
+  '    if ([string]::IsNullOrEmpty($name)) { continue }',
+  '    $norm = $name -replace "\\\\","/"',
+  '    if ($norm.StartsWith("/") -or $norm.StartsWith("//")) {',
+  '      [Console]::Error.WriteLine("Refusing absolute/UNC entry: " + $name); exit 3',
+  '    }',
+  '    if ($name -match "^[A-Za-z]:[\\\\/]") {',
+  '      [Console]::Error.WriteLine("Refusing Windows-absolute entry: " + $name); exit 3',
+  '    }',
+  '    foreach ($part in ($norm -split "/")) {',
+  '      if ($part -eq "..") {',
+  '        [Console]::Error.WriteLine("Refusing parent-traversal entry: " + $name); exit 3',
+  '      }',
+  '    }',
+  '    $target = [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($destFull, $norm))',
+  '    if (-not $target.StartsWith($destFull, [System.StringComparison]::OrdinalIgnoreCase)) {',
+  '      [Console]::Error.WriteLine("Entry escapes destination: " + $name); exit 3',
+  '    }',
+  '    if ($entry.FullName.EndsWith("/")) {',
+  '      [System.IO.Directory]::CreateDirectory($target) | Out-Null',
+  '    } else {',
+  '      $parent = [System.IO.Path]::GetDirectoryName($target)',
+  '      if ($parent) { [System.IO.Directory]::CreateDirectory($parent) | Out-Null }',
+  '      [System.IO.Compression.ZipFileExtensions]::ExtractToFile($entry, $target, $true)',
+  '    }',
+  '  }',
+  '} finally {',
+  '  $zip.Dispose()',
+  '}'
+].join('\r\n');
+
+/**
+ * Extract a zip buffer into a scratch directory.
+ *
+ * The extraction runs a PowerShell helper script via `-File` so PowerShell
+ * never re-parses a command string (which would break on paths containing
+ * spaces or brackets). The script reads the zip and destination paths from
+ * environment variables, validates every entry's path before extracting, and
+ * writes files individually using .NET's ZipFile APIs.
+ *
+ * After extraction, `walkFiles` re-checks the tree and rejects any symlink
+ * or junction that might have been created.
+ *
+ * @param {Buffer} buf
+ * @returns {Promise<string>} scratch dir
+ */
+async function extractZipToScratch(buf) {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-analyzer-zip-'));
+  const tmpZip = path.join(scratch, '__archive.zip');
+  const scriptDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-analyzer-ps-'));
+  const scriptPath = path.join(scriptDir, 'extract.ps1');
+
+  try {
+    fs.writeFileSync(tmpZip, buf);
+    fs.writeFileSync(scriptPath, EXTRACT_ZIP_PS1, 'utf8');
+
+    await new Promise(function(resolve, reject) {
+      const child = cp.execFile(
+        'powershell.exe',
+        [
+          '-NoProfile',
+          '-NonInteractive',
+          '-ExecutionPolicy', 'Bypass',
+          '-File', scriptPath
+        ],
+        {
+          windowsHide: true,
+          env: Object.assign({}, process.env, {
+            SRC_ZIP: tmpZip,
+            DEST_DIR: scratch
+          })
+        },
+        function(err, _stdout, stderr) {
+          if (err) {
+            reject(new Error('zip extraction failed: ' + (stderr || err.message)));
+          } else {
+            resolve();
+          }
+        }
+      );
+      // Do not write to stdin; the script reads from env.
+      if (child.stdin) child.stdin.end();
     });
-    ps.on('error', reject);
-  });
+
+    try { fs.unlinkSync(tmpZip); } catch (e) { /* ignore */ }
+
+    // Defense in depth: walkFiles() throws on any symlink/junction. Also
+    // confirm every file resolves inside scratch.
+    const files = walkFiles(scratch);
+    for (let i = 0; i < files.length; i++) {
+      assertInsideRoot(scratch, files[i]);
+    }
+  } catch (err) {
+    rmrf(scratch);
+    throw err;
+  } finally {
+    rmrf(scriptDir);
+  }
+
+  return scratch;
+}
+
+/**
+ * Find the expected binary inside a scratch directory (recursive search).
+ * @param {string} scratch
+ * @param {string} binaryBaseName e.g. `agent-analyzer` or `agent-analyzer.exe`
+ * @returns {string|null} absolute path, or null if not found
+ */
+function findBinaryInScratch(scratch, binaryBaseName) {
+  const files = walkFiles(scratch);
+  for (let i = 0; i < files.length; i++) {
+    if (path.basename(files[i]) === binaryBaseName) {
+      assertInsideRoot(scratch, files[i]);
+      return files[i];
+    }
+  }
+  return null;
 }
 
+// ---------------------------------------------------------------------------
+// Download + install
+// ---------------------------------------------------------------------------
+
 /**
  * Download and install the binary for the current platform into ~/.agent-sh/bin/.
  * @param {string} ver
- * @returns {Promise<string>}
+ * @param {Object} [options]
+ * @param {boolean} [options.skipChecksum=false] LOCAL DEV ONLY. Skips the
+ *   `.sha256` sidecar fetch and verification. NEVER set this in production.
+ * @returns {Promise<string>} path to the installed binary
  */
-async function downloadBinary(ver) {
+async function downloadBinary(ver, options) {
+  const opts = options || {};
+  const skipChecksum = opts.skipChecksum === true;
+
   const platformKey = getPlatformKey();
   if (!platformKey) {
     throw new Error(
@@ -250,12 +597,14 @@ async function downloadBinary(ver) {
   }
 
   const url = buildDownloadUrl(ver, platformKey);
-  process.stderr.write('Downloading ' + BINARY_NAME + ' v' + ver + ' for ' + platformKey + '...' + '\n');
+  const filename = url.substring(url.lastIndexOf('/') + 1);
+  process.stderr.write('Downloading ' + BINARY_NAME + ' v' + ver + ' for ' + platformKey + '...\n');
 
   const binPath = getBinaryPath();
   const binDir = path.dirname(binPath);
   fs.mkdirSync(binDir, { recursive: true });
 
+  // --- 1. Fetch archive bytes --------------------------------------------
   let buf;
   try {
     buf = await downloadToBuffer(url);
@@ -271,10 +620,53 @@ async function downloadBinary(ver) {
     );
   }
 
-  if (process.platform === 'win32') {
-    await extractZip(buf, binDir, path.basename(binPath));
+  // --- 2. Verify SHA-256 sidecar -----------------------------------------
+  if (skipChecksum) {
+    process.stderr.write(
+      '[WARN] skipChecksum=true - SHA-256 verification disabled. ' +
+      'This is LOCAL DEV ONLY and MUST NOT be used in production.\n'
+    );
   } else {
-    await extractTarGz(buf, binDir);
+    let expected;
+    try {
+      expected = await downloadSha256(url);
+    } catch (err) {
+      throw new Error(
+        'Failed to fetch SHA-256 sidecar for ' + filename + ':\n' +
+        '  URL: ' + url + '.sha256\n' +
+        '  Error: ' + err.message + '\n\n' +
+        'The release may be missing its checksum file. Refusing to install ' +
+        'an unverified binary. If this is a legacy release without sidecars, ' +
+        'pass { skipChecksum: true } to downloadBinary() (LOCAL DEV ONLY).'
+      );
+    }
+    verifySha256(buf, expected, filename);
+  }
+
+  // --- 3. Extract to isolated scratch dir + validate entries -------------
+  const binaryBaseName = path.basename(binPath);
+  let scratch;
+  try {
+    if (process.platform === 'win32') {
+      scratch = await extractZipToScratch(buf);
+    } else {
+      scratch = await extractTarGzToScratch(buf);
+    }
+
+    // --- 4. Locate the expected binary inside scratch --------------------
+    const extractedBin = findBinaryInScratch(scratch, binaryBaseName);
+    if (!extractedBin) {
+      throw new Error(
+        'Expected binary "' + binaryBaseName + '" not found inside archive ' +
+        filename + '. Archive layout may have changed.'
+      );
+    }
+
+    // --- 5. Move ONLY the expected binary to its final location ----------
+    // copyFileSync so cross-device moves work. scratch is rmrf'd in finally.
+    fs.copyFileSync(extractedBin, binPath);
+  } finally {
+    if (scratch) rmrf(scratch);
   }
 
   if (process.platform !== 'win32') {
@@ -300,6 +692,7 @@ async function downloadBinary(ver) {
  * Ensure the binary exists and meets the minimum version. Downloads if needed.
  * @param {Object} [options]
  * @param {string} [options.version]
+ * @param {boolean} [options.skipChecksum=false] LOCAL DEV ONLY.
  * @returns {Promise<string>}
  */
 async function ensureBinary(options) {
@@ -314,7 +707,7 @@ async function ensureBinary(options) {
     }
   }
 
-  return downloadBinary(targetVer);
+  return downloadBinary(targetVer, { skipChecksum: opts.skipChecksum === true });
 }
 
 /**
@@ -322,6 +715,7 @@ async function ensureBinary(options) {
  * Prefer ensureBinary() unless a sync API is strictly required.
  * @param {Object} [options]
  * @param {string} [options.version]
+ * @param {boolean} [options.skipChecksum=false] LOCAL DEV ONLY.
  * @returns {string}
  */
 function ensureBinarySync(options) {
@@ -335,10 +729,12 @@ function ensureBinarySync(options) {
   }
 
   const targetVer = (options && options.version) || ANALYZER_MIN_VERSION;
+  const skipChecksum = !!(options && options.skipChecksum);
   const selfPath = __filename;
   const helperLines = [
     'var b = require(' + JSON.stringify(selfPath) + ');',
-    'b.ensureBinary({ version: ' + JSON.stringify(targetVer) + ' })',
+    'b.ensureBinary({ version: ' + JSON.stringify(targetVer) +
+      ', skipChecksum: ' + JSON.stringify(skipChecksum) + ' })',
     '  .then(function(p) { process.stdout.write(p); })',
     '  .catch(function(e) { process.stderr.write(e.message); process.exit(1); });'
   ];
@@ -394,5 +790,16 @@ module.exports = {
   isAvailableAsync,
   meetsMinimumVersion,
   buildDownloadUrl,
-  PLATFORM_MAP
+  PLATFORM_MAP,
+  // Exported for tests + advanced consumers
+  parseSha256Sidecar,
+  verifySha256,
+  sha256Hex,
+  assertSafeArchiveEntry,
+  assertInsideRoot,
+  downloadBinary,
+  // Exported for tests only
+  extractTarGzToScratch,
+  extractZipToScratch,
+  _EXTRACT_ZIP_PS1: EXTRACT_ZIP_PS1
 };

package/lib/cross-platform/index.js

@@ -303,17 +303,19 @@ function formatSection(title, content) {
  */
 
 /**
- * Truncate text to limit with ellipsis
+ * Truncate text to limit with ellipsis.
+ *
+ * Slices on Unicode code points (not UTF-16 code units) so multi-byte
+ * chars like emoji never end up as orphan surrogates. Non-positive
+ * maxLength returns the original string unchanged.
  *
  * @param {string} text - Text to truncate
- * @param {number} maxLength - Maximum length
+ * @param {number} maxLength - Maximum length (in code points)
  * @returns {string} Truncated text
  */
 function truncate(text, maxLength) {
-  // Negative or zero maxLength: return original text unchanged
   if (maxLength <= 0) return text;
-  // Use Array.from to iterate over code points (handles emoji/surrogate pairs)
-  const codePoints = Array.from(text);
+  const codePoints = [...text];
   if (codePoints.length <= maxLength) return text;
   return codePoints.slice(0, maxLength - 3).join('') + '...';
 }

package/lib/enhance/fixer.js

@@ -7,6 +7,37 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Reject symlinks before read/write operations.
+ *
+ * Security: A hostile repo could symlink a fixable file (e.g. `agent.md`) to a
+ * sensitive target (e.g. `~/.ssh/authorized_keys`). A HIGH-certainty auto-fix
+ * would then silently overwrite that target. We refuse to follow symlinks on
+ * any path we intend to read from or write to, including `.backup` siblings.
+ *
+ * This is called both before opening and immediately before writing, which
+ * narrows - though does not fully close - the TOCTOU window between calls.
+ * Node's fs module does not expose a portable `O_NOFOLLOW` open flag, so
+ * repeated lstat is the cleanest available mitigation for text-file edits.
+ *
+ * @param {string} targetPath - Path to check.
+ * @throws {Error} If the path exists and is a symlink.
+ */
+function assertNotSymlink(targetPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(targetPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // Path does not yet exist - fine.
+    throw err;
+  }
+  if (stat.isSymbolicLink()) {
+    const err = new Error('target is a symlink; refusing to follow');
+    err.code = 'ESYMLINK_REFUSED';
+    throw err;
+  }
+}
+
 function applyFixes(issues, options = {}) {
   const { dryRun = false, backup = true } = options;
 
@@ -59,6 +90,23 @@ function applyFixes(issues, options = {}) {
         continue;
       }
 
+      // Security: refuse symlinks before we read, so a hostile repo can't
+      // redirect a HIGH-certainty fix at ~/.ssh/authorized_keys or similar.
+      try {
+        assertNotSymlink(filePath);
+      } catch (err) {
+        if (err.code === 'ESYMLINK_REFUSED') {
+          results.errors.push({
+            filePath,
+            error: err.message,
+            success: false,
+            reason: 'target is a symlink; refusing to follow'
+          });
+          continue;
+        }
+        throw err;
+      }
+
       const content = fs.readFileSync(filePath, 'utf8');
       let data;
 
@@ -135,6 +183,8 @@ function applyFixes(issues, options = {}) {
         // Create backup
         if (backup) {
           const backupPath = `${filePath}.backup`;
+          // Refuse if the backup slot itself is a pre-existing symlink.
+          assertNotSymlink(backupPath);
           fs.writeFileSync(backupPath, content, 'utf8');
         }
 
@@ -145,6 +195,11 @@ function applyFixes(issues, options = {}) {
         } else {
           newContent = JSON.stringify(modified, null, 2);
         }
+        // Re-check immediately before write. Narrows the TOCTOU window
+        // between the initial lstat and this writeFileSync (an attacker
+        // who swaps the regular file for a symlink between calls will
+        // be caught here).
+        assertNotSymlink(filePath);
         fs.writeFileSync(filePath, newContent, 'utf8');
       }
 
@@ -280,7 +335,14 @@ function restoreFromBackup(filePath) {
     return false;
   }
 
+  // Security: refuse if either the backup or the restore target is a
+  // symlink. Same threat model as applyFixes - a malicious post-hoc swap
+  // could redirect the restore at a sensitive file.
+  assertNotSymlink(backupPath);
+  assertNotSymlink(filePath);
+
   const backupContent = fs.readFileSync(backupPath, 'utf8');
+  assertNotSymlink(filePath);
   fs.writeFileSync(filePath, backupContent, 'utf8');
   fs.unlinkSync(backupPath);
 
@@ -717,5 +779,6 @@ module.exports = {
   fixAggressiveEmphasis,
   previewFixes,
   restoreFromBackup,
-  cleanupBackups
+  cleanupBackups,
+  assertNotSymlink
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.9.1",
+  "version": "5.11.0",
   "description": "A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI",
   "main": "lib/platform/detect-platform.js",
   "type": "commonjs",
@@ -81,7 +81,6 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "agentsys": "^5.0.0",
     "js-yaml": "~4.1.1"
   },
   "devDependencies": {

package/scripts/pin-marketplace.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Pin each marketplace sub-plugin entry to a release tag (and commit SHA for
+ * defense in depth). Falls back to pinning current default-branch HEAD when a
+ * release tag for the declared `version` does not exist on the remote.
+ *
+ * Rationale: unpinned `source: "url"` entries let `claude plugin install`
+ * track the default branch, which is a supply-chain compromise vector. Pinning
+ * to a tag (for humans) AND the tag's resolved commit SHA (for integrity)
+ * ensures the exact bytes we ship are the exact bytes users get.
+ *
+ * Usage: node scripts/pin-marketplace.js [--dry-run]
+ *
+ * Requires: `gh` CLI authenticated against the agent-sh org.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const MARKETPLACE_PATH = path.join(
+  __dirname,
+  '..',
+  '.claude-plugin',
+  'marketplace.json',
+);
+
+// Seam for tests: callers may override `ghRunner` to stub API responses.
+let ghRunner = defaultGhRunner;
+
+function defaultGhRunner(args) {
+  try {
+    return execFileSync('gh', args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch (err) {
+    const stderr = err.stderr ? err.stderr.toString() : '';
+    const e = new Error(`gh ${args.join(' ')} failed: ${stderr || err.message}`);
+    e.stderr = stderr;
+    throw e;
+  }
+}
+
+function gh(args) {
+  return ghRunner(args);
+}
+
+function setGhRunner(fn) {
+  ghRunner = typeof fn === 'function' ? fn : defaultGhRunner;
+}
+
+function parseOrgRepo(gitUrl) {
+  // https://github.com/agent-sh/<name>.git    -> ["agent-sh", "<name>"]
+  // https://github.com/agent-sh/<name>        -> ["agent-sh", "<name>"]
+  // https://github.com/agent-sh/<name>/       -> ["agent-sh", "<name>"]
+  // https://github.com/agent-sh/<name>/.git   -> ["agent-sh", "<name>"]
+  // git@github.com:agent-sh/<name>.git        -> ["agent-sh", "<name>"]
+  const m = gitUrl.match(
+    /github\.com[:/]+([^/]+)\/([^/]+?)\/?(?:\.git)?\/?$/,
+  );
+  if (!m) throw new Error(`Cannot parse org/repo from ${gitUrl}`);
+  return { owner: m[1], repo: m[2] };
+}
+
+function resolveTagSha(owner, repo, tag) {
+  // Returns the commit SHA the tag resolves to, or null if tag is missing.
+  // Uses the singular `git/ref/tags/<tag>` endpoint to get an exact match;
+  // the plural `git/refs/tags/<tag>` does prefix matching and can silently
+  // return an array when multiple tags share a prefix.
+  // Tags may be annotated (object.type === "tag") or lightweight. Annotated
+  // tags need a second deref step to the underlying commit.
+  let ref;
+  try {
+    ref = JSON.parse(
+      gh(['api', `repos/${owner}/${repo}/git/ref/tags/${tag}`]),
+    );
+  } catch (err) {
+    if (/Not Found|404/i.test(err.stderr || err.message)) return null;
+    throw err;
+  }
+  // Defense in depth: reject unexpected array responses as ambiguous so a
+  // future endpoint-behavior shift cannot silently pick the wrong tag.
+  if (Array.isArray(ref)) {
+    throw new Error(
+      `Ambiguous tag lookup for ${owner}/${repo}@${tag}: got array of ${ref.length} refs`,
+    );
+  }
+  if (!ref || !ref.object) return null;
+  if (ref.object.type === 'commit') return ref.object.sha;
+  if (ref.object.type === 'tag') {
+    const annotated = JSON.parse(
+      gh(['api', `repos/${owner}/${repo}/git/tags/${ref.object.sha}`]),
+    );
+    return annotated.object && annotated.object.sha
+      ? annotated.object.sha
+      : null;
+  }
+  return null;
+}
+
+function defaultBranchHeadSha(owner, repo) {
+  // Use HEAD (which the API resolves to the repo's default branch) rather
+  // than hardcoding `main`. Works even if the repo still ships `master` or
+  // adopts something else later.
+  return gh([
+    'api',
+    `repos/${owner}/${repo}/commits/HEAD`,
+    '--jq',
+    '.sha',
+  ]);
+}
+
+function pinPlugin(plugin) {
+  const src = plugin.source;
+  if (!src || src.source !== 'url' || !src.url) {
+    return { status: 'skipped', name: plugin.name };
+  }
+
+  const { owner, repo } = parseOrgRepo(src.url);
+  const version = plugin.version;
+  const tag = version ? `v${version}` : null;
+
+  let sha = null;
+  if (tag) {
+    sha = resolveTagSha(owner, repo, tag);
+  }
+
+  if (sha) {
+    src.ref = tag;
+    src.commit = sha;
+    return { status: 'pinned', name: plugin.name, tag, sha };
+  }
+
+  const head = defaultBranchHeadSha(owner, repo);
+  // Explicitly clear any stale `ref` from a previous run: if the plugin
+  // loses its tag (e.g., deleted for a security rewrite) we must not leave
+  // the old tag reference around, since downstream installers that prefer
+  // `ref` would otherwise ignore the new commit pin.
+  delete src.ref;
+  src.commit = head;
+  return { status: 'fallback', name: plugin.name, wantedTag: tag, sha: head };
+}
+
+function main() {
+  const raw = fs.readFileSync(MARKETPLACE_PATH, 'utf8');
+  const data = JSON.parse(raw);
+
+  const pinned = [];
+  const fallbacks = [];
+  const errors = [];
+
+  for (const plugin of data.plugins) {
+    try {
+      const result = pinPlugin(plugin);
+      if (result.status === 'pinned') {
+        pinned.push(result);
+        console.log(
+          `[OK] ${result.name} -> ${result.tag} (${result.sha.slice(0, 10)})`,
+        );
+      } else if (result.status === 'fallback') {
+        fallbacks.push(result);
+        console.log(
+          `[WARN] ${result.name} has no tag ${result.wantedTag}; pinning default-branch@${result.sha.slice(0, 10)}`,
+        );
+      }
+    } catch (err) {
+      errors.push({ name: plugin.name, error: err.message });
+      console.error(`[ERROR] ${plugin.name}: ${err.message}`);
+    }
+  }
+
+  const out = JSON.stringify(data, null, 2) + '\n';
+
+  if (DRY_RUN) {
+    console.log('\n[DRY-RUN] Not writing marketplace.json');
+  } else if (errors.length === 0) {
+    fs.writeFileSync(MARKETPLACE_PATH, out);
+    console.log(`\n[OK] Wrote ${MARKETPLACE_PATH}`);
+  } else {
+    console.log(
+      '\n[WARN] Not writing marketplace.json because some plugins failed; re-run after resolving errors.',
+    );
+  }
+
+  console.log(
+    `\nSummary: ${pinned.length} pinned to tags, ${fallbacks.length} fell back to default-branch SHA, ${errors.length} errors`,
+  );
+  if (fallbacks.length > 0) {
+    console.log('\nFallback plugins (no release tag yet):');
+    for (const f of fallbacks) {
+      console.log(`  - ${f.name}: wanted ${f.wantedTag}, pinned ${f.sha}`);
+    }
+  }
+  if (errors.length > 0) {
+    console.log('\nFailed plugins:');
+    for (const e of errors) {
+      console.log(`  - ${e.name}: ${e.error}`);
+    }
+    return 1;
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    const code = main();
+    process.exit(code);
+  } catch (err) {
+    console.error(`[ERROR] ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parseOrgRepo,
+  resolveTagSha,
+  defaultBranchHeadSha,
+  pinPlugin,
+  setGhRunner,
+};

package/site/content.json

@@ -5,7 +5,7 @@
     "url": "https://agent-sh.github.io/agentsys",
     "repo": "https://github.com/agent-sh/agentsys",
     "npm": "https://www.npmjs.com/package/agentsys",
-    "version": "5.9.1",
+    "version": "5.11.0",
     "author": "Avi Fenesh",
     "author_url": "https://github.com/avifenesh"
   },