@ssheleg/agent-sync 1.18.4 → 1.18.6

package/CHANGELOG.md

@@ -1,3 +1,82 @@
+## v1.18.6 — the guard keeps its own header's promise, and /clear gets its own identity
+
+Wave-2 hardening from the 2026-08-29 family audit (ASY-07, ASY-08, ASY-06, ASY-01).
+Same shape as v1.18.5: text that claimed more than the code did.
+
+- **ASY-07 — a machine without python3 had no guard, and said nothing.** `guard.sh`'s
+  header promises that every internal failure exits 2, because any other outcome is
+  non-blocking in Claude Code — and the python3-absent path broke it: both parser
+  substitutions failed under `2>/dev/null`, `path` came back empty, `is_commit`
+  defaulted to 0 and the hook exited 0. Fail OPEN, exactly where the header says it
+  must not, and nothing upstream compensates — hooks.json's `if` filter is best-effort
+  by doctrine, so the parser IS the guard. Both substitutions now report through
+  `parser_or_die`, which exits 2 and names the remedy (install python3 / fix PATH, or
+  remove `.claude/agent-sync.json` to switch coordination off).
+  `check_guard_fails_closed_without_python3` drives the real hook through a shim PATH
+  holding bash and cat but no interpreter — watched failing against the shipped guard
+  (`the guard exited 0`) — and the self-test plants the fail-open back
+  (`an absent interpreter fails open`).
+- **ASY-08 — a post-/clear session inherited the ended run's identity.** The
+  SessionStart matcher read `startup|resume`, and `/clear` ends the run while keeping
+  the CLI process — so the stamp keyed by that process survived into the next session:
+  "two sessions, one identity", the case SKILL.md itself names, and `release` then
+  takes a lease the caller never had. The matcher now carries `clear`; `compact` stays
+  excluded deliberately, because a compaction continues the SAME session.
+  `hooks_session_test.py` gained the case (matcher parts asserted both directions, and
+  the hook re-stamps on a clear payload) — watched failing against the shipped matcher.
+- **ASY-06 — the guard's internal-failure refusal named no next step.** A refusal with
+  no remedy is how an operator learns to switch a hook off. The message now says:
+  diagnose with `python3 <script> check`, or acquire a lease first.
+- **ASY-01 — `scripts/__pycache__` regenerated forever.** Hooks now export
+  `PYTHONDONTWRITEBYTECODE=1` in `_lib.sh` (sourced by all four), and the test files
+  that import `agent_sync.py` set `sys.dont_write_bytecode` — the shipped `scripts/`
+  directory stays source, not build products.
+- ASY-04 (this test class missing from CI) was already closed in v1.18.5:
+  `validate.yml` runs `hooks_session_test.py` since commit `5446990`. Verified, not
+  re-done. ASY-02 (command rename) closed by operator decision 2026-08-30: names stay.
+
+## v1.18.5 — a pipe reaches the guard, and the installers stop deleting blind
+
+Two enforcement holes, each of the same shape: a mechanism whose own text claimed more
+than its code did.
+
+- **ASY-05 — a piped commit bypassed the lease guard entirely.** `guard.sh`'s tokenizer
+  said "each `&&`/`;`/`|` segment is its own command" and consumed only `&&`, `;` and
+  `||` — so `echo msg | git commit -F -`, the ordinary way to commit a generated
+  message, was one segment whose first token is `echo`, and the whole pipeline skipped
+  the guard. The single pipe and `|&` are now consumed (ordered after `||`, or each
+  would shatter into stray halves), three new `GUARD_SHAPES` cover the bypass and the
+  pipe that must NOT block (`git log | grep commit`), and the self-test plants the
+  shipped tokenizer back (`a piped commit slips past the guard`). Watched failing
+  against the pre-fix guard: both piped shapes reached a guarded file with exit 0.
+- **The installers consulted nothing before deleting the Claude Code channel.** This
+  member's installers never write `~/.claude/skills/agent-sync` themselves — the skills
+  CLI they drive recreates it — and both deleted that copy unconditionally afterwards.
+  The family canon this implements (make-skill v0.25.0, distribution.md §3) names the
+  fail-open class, and here it ran in mirror image: on a home where the plugin is NOT
+  installed — no claude CLI, or the plugin install failed — the prune destroyed the only
+  Claude Code channel the very same run had just installed, and exited 0. The fate of
+  the copy is now a decision read from the target home's
+  `~/.claude/plugins/installed_plugins.json` (the record of what is installed; plugin
+  and marketplace names differ, so the spec is taken from the JSON), with the
+  `marketplaces/<name>` dir kept only as the fallback signal: plugin present → the
+  shadow is pruned and the message names the real spec, the plugin-channel remedy and
+  the family launcher; no plugin → the copy is kept, because it IS the Claude Code
+  channel; `--force` → kept beside the plugin, as the recorded choice to run two
+  channels where the stale one wins. Absent or corrupt JSON reads as "no plugin" — fail
+  open, never crash. Only the Claude Code channel is gated; other agents' installs are
+  untouched.
+- **The install now says how the next version arrives** — `npx @ssheleg/agent-sync@latest
+  update`, or the family launcher — because an installer that never mentions updates has
+  still chosen an update model: never.
+- `test/installer_test.js`: 11 cases against throwaway HOMEs with the delegated CLIs
+  stubbed through PATH — plugin-present prune with the spec from the JSON, a
+  differently-named marketplace, `--force`, corrupt JSON, a prefix-collider
+  (`agent-sync-extra@x`), the marketplaces-dir fallback, the update path, and the
+  install.sh mirrors. Ten of eleven watched failing against the pre-fix installers.
+  Wired into `npm test` and CI; `hooks_session_test.py` — already in `npm test` —
+  joins CI in the same step block.
+
 ## v1.18.4 — the channel that sends the installs, on npm too
 
 - The `skills.sh` badge and the canonical `homepage` reached GitHub in the previous cycle and stopped

package/bin/agent-sync.js

@@ -6,8 +6,11 @@
  *
  * One channel per agent: Claude Code gets the plugin, every other agent gets the
  * skill through the vercel skills CLI, and the plain ~/.claude/skills/agent-sync
- * copy that the skills CLI recreates on its own is pruned afterwards — that
- * duplicate shadows the plugin and silently serves a stale skill.
+ * copy that the skills CLI recreates on its own is settled afterwards against
+ * the home's installed_plugins.json — pruned when the plugin owns Claude Code
+ * (the duplicate would shadow it and silently serve a stale skill), kept when no
+ * plugin does (then it IS the Claude Code channel), kept on --force as the
+ * recorded choice to run two channels. Canon: make-skill distribution.md §3.
  */
 
 const { spawnSync } = require('child_process');
@@ -19,6 +22,41 @@ const REPO = 'ssheleg/agent-sync';
 const NAME = 'agent-sync';
 const SHADOW = path.join(os.homedir(), '.claude', 'skills', NAME);
 
+/**
+ * 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 — the only signal the family's
+ * installers read until the 2026-08-29 canon (make-skill v0.25.0,
+ * distribution.md §3) — 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;
+}
+
 const C = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
@@ -46,7 +84,12 @@ ${C.bold('agent-sync')} — coordination for concurrent agents
   npx @ssheleg/${NAME} install              install for Claude Code and other agents
   npx @ssheleg/${NAME} install --claude-only  Claude Code plugin only
   npx @ssheleg/${NAME} install --agent a,b    pick agents for the skills CLI
-  npx @ssheleg/${NAME} update               update every channel, then prune the shadow
+  npx @ssheleg/${NAME} update               update every channel, then settle the
+                                            ~/.claude/skills copy: pruned when it
+                                            would shadow the installed plugin, kept
+                                            when no plugin owns Claude Code
+  npx @ssheleg/${NAME} install|update --force  keep the plain copy even beside the
+                                            plugin — two channels, the stale one wins
   npx @ssheleg/${NAME} --help
 
 After installing, initialise the project — this is the step that asks where
@@ -64,6 +107,7 @@ asks for a token and never stores one.
 function install(argv) {
   const claudeOnly = argv.includes('--claude-only');
   const noClaude = argv.includes('--no-claude');
+  const force = argv.includes('--force');
   const agentIdx = argv.indexOf('--agent');
   const agents = agentIdx !== -1 && argv[agentIdx + 1] ? argv[agentIdx + 1].split(',') : null;
 
@@ -88,7 +132,7 @@ function install(argv) {
     ok = run('npx', args) && ok;
   }
 
-  pruneShadow();
+  settleClaudeChannel(force);
 
   console.log(
     ok
@@ -98,8 +142,14 @@ function install(argv) {
   // Before the "Next:" block, so the last thing on screen stays the instruction
   // rather than the tail of a delegated command.
   offerRouters();
+  // How the next version arrives — an installer that never says has still
+  // chosen an update model: never.
   console.log(`
-${C.bold('Next:')} restart Claude Code, then run ${C.bold('/agent-sync init')} in your project.
+${C.bold('Updates:')} npx @ssheleg/${NAME}@latest update — every channel, and it settles
+the plain copy that would shadow the plugin. Whole family:
+npx --yes sshlg-skills@latest update.
+`);
+  console.log(`${C.bold('Next:')} restart Claude Code, then run ${C.bold('/agent-sync init')} in your project.
 It will ask where coordination state should live before writing anything.
 `);
   return ok ? 0 : 1;
@@ -137,13 +187,30 @@ function offerRouters() {
 }
 
 /**
+ * Decide the fate of ~/.claude/skills/<name> after a skills-CLI run.
+ *
  * The shadow regrows on its own: `npx skills add|update --global` auto-detects
  * Claude Code and recreates ~/.claude/skills/<name> — often as a symlink — even when
- * claude-code was never named as a target. That copy shadows the plugin and serves a
- * stale skill, so the prune belongs INSIDE every command that touches the skills CLI,
- * not in a human's memory. lstatSync, because a symlink shadows exactly as a dir does.
+ * claude-code was never named as a target. What that copy IS depends on the home it
+ * landed in, and until v1.18.5 this function consulted nothing and deleted it
+ * unconditionally — the family's fail-open class (make-skill distribution.md §3) in
+ * mirror image: on a home where the plugin is NOT installed (no claude CLI, or the
+ * plugin install failed), the unconditional prune destroyed the only Claude Code
+ * channel this very run had just installed, and exited 0.
+ *
+ * - Plugin installed in this home — read from installed_plugins.json, with the
+ *   marketplaces/<name> dir kept only as the fallback signal: the copy is a SHADOW.
+ *   It outranks the plugin and serves the version it was copied from forever.
+ *   Prune it, and name the plugin spec it would have shadowed plus the channel
+ *   that owns updates.
+ * - No plugin: the copy is Claude Code's only channel. Keep it, and say so.
+ * - --force: the deliberate choice to run two channels, where the stale one wins.
+ *   The copy stays even beside the plugin, and the output records the choice.
+ *
+ * The gate lives INSIDE every command that touches the skills CLI, not in a human's
+ * memory. lstatSync, because a symlink shadows exactly as a dir does.
  */
-function pruneShadow() {
+function settleClaudeChannel(force) {
   let present = false;
   try {
     fs.lstatSync(SHADOW);
@@ -152,11 +219,40 @@ function pruneShadow() {
     /* not there */
   }
   if (!present) return;
+
+  const home = os.homedir();
+  const spec = installedPluginSpec(home, NAME);
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', NAME);
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+
+  if (!spec && !viaMarketplaceDir) {
+    console.log(C.dim(
+      `  kept ${SHADOW} — no ${NAME} plugin is installed in this home,\n` +
+      `  so this plain copy is Claude Code's only channel for the skill`));
+    return;
+  }
+  if (force) {
+    console.log(C.yellow(
+      `  kept ${SHADOW} beside the installed plugin (--force) — two channels\n` +
+      `  on one agent, and the stale plain copy is the one Claude Code reads`));
+    return;
+  }
+  const found = spec
+    ? `the Claude Code plugin ${spec} is installed (installed_plugins.json)`
+    : `a Claude Code marketplace is registered at ${marketplace}`;
   fs.rmSync(SHADOW, { recursive: true, force: true });
-  console.log(C.dim(`  pruned duplicate ${SHADOW}`));
+  console.log(C.dim(
+    `  pruned ${SHADOW} — ${found};\n` +
+    `  a plain copy there would shadow the plugin and serve a frozen version\n` +
+    `  forever. The plugin channel owns updates:\n` +
+    `    claude plugin marketplace update ${NAME}\n` +
+    `    claude plugin update ${spec || `${NAME}@${NAME}`}\n` +
+    `  Pass --force to keep the plain copy anyway — a deliberate choice to run\n` +
+    `  two channels, where the stale one wins.`));
 }
 
-function update() {
+function update(argv) {
+  const force = argv.includes('--force');
   console.log(C.bold('\nUpdating every channel'));
   let ok = true;
   if (has('claude')) {
@@ -166,7 +262,7 @@ function update() {
     ok = run('claude', ['plugin', 'update', `${NAME}@${NAME}`]) && ok;
   }
   ok = run('npx', ['--yes', 'skills', 'update', NAME, '--global', '--yes']) && ok;
-  pruneShadow();
+  settleClaudeChannel(force);
   console.log(ok ? C.green('\n✓ updated') : C.red('\n✗ a channel failed — see above'));
   console.log('\nRestart Claude Code so it picks the new version up.');
   return ok ? 0 : 1;
@@ -178,6 +274,6 @@ if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
   process.exit(0);
 }
 if (argv[0] === 'install') process.exit(install(argv.slice(1)));
-if (argv[0] === 'update') process.exit(update());
+if (argv[0] === 'update') process.exit(update(argv.slice(1)));
 usage();
 process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.18.4",
+  "version": "1.18.6",
   "description": "Let concurrent coding agents share one project without colliding — leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py && python3 test/hooks_session_test.py",
+    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py && python3 test/hooks_session_test.py && node test/installer_test.js",
     "prepublishOnly": "python3 test/validate.py"
   },
   "publishConfig": {

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

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.18.4",
+  "version": "1.18.6",
   "description": "Coordination layer for multi-agent repositories — leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
     "name": "ssheleg",

package/plugins/agent-sync/hooks/_lib.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 # Shared helpers for the agent-sync hooks. Sourced, never executed.
 
+# Every hook runs python3 against the shipped scripts/ directory, which people read
+# as source, not as a build product. Bytecode caching buys nothing at this call rate
+# and left scripts/__pycache__ regenerating forever (ASY-01).
+export PYTHONDONTWRITEBYTECODE=1
+
 # Run a command under a time limit, portably.
 #
 # `timeout` is GNU coreutils and is NOT on a stock macOS. Calling it directly made

package/plugins/agent-sync/hooks/guard.sh

@@ -8,6 +8,17 @@ S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
 input=$(cat)
 
+# The parser IS the guard: hooks.json's `if` filter is best-effort and fails open by
+# doctrine, so nothing upstream compensates for a parser that cannot run. A python3
+# missing from PATH used to leave `path` empty, default `is_commit` to 0 and exit 0 —
+# the one machine state that disables the parser silently disabled the guard (ASY-07).
+parser_or_die() {
+  local rc="$1"
+  [ "$rc" -eq 0 ] && return 0
+  echo "agent-sync: the guard could not run its parser (python3 exit $rc — likely missing from PATH). Failing closed. Install python3 or fix PATH and retry, or remove .claude/agent-sync.json to switch coordination off here." >&2
+  exit 2
+}
+
 path=$(python3 -c '
 import json,sys
 try:
@@ -17,6 +28,7 @@ except Exception:
 ti=d.get("tool_input") or {}
 print(ti.get("file_path") or ti.get("path") or ti.get("notebook_path") or "")
 ' <<<"$input" 2>/dev/null)
+parser_or_die $?
 
 # git commit: check every staged path instead of a single file argument.
 if [ -z "$path" ]; then
@@ -30,7 +42,7 @@ if [ -z "$path" ]; then
   #
   # Tokenised in python rather than globbed in shell: `git log --grep=commit` must not match, and
   # `git -c user.name=x -C dir commit` must.
-  read -r is_commit repo <<<"$(python3 -c '
+  parsed=$(python3 -c '
 import json, shlex, sys
 try:
     d = json.load(sys.stdin)
@@ -38,8 +50,12 @@ except Exception:
     print("0 ."); sys.exit(0)
 cmd = (d.get("tool_input") or {}).get("command", "")
 is_commit, repo = 0, "."
-# Each &&/;/| segment is its own command; a commit anywhere in the chain counts.
-for seg in cmd.replace("&&", "\n").replace(";", "\n").replace("||", "\n").split("\n"):
+# Each &&/;/||/|&/| segment is its own command; a commit anywhere in the chain counts.
+# The single pipe was CLAIMED by this comment and never consumed (ASY-05, fixed 2026-08-29):
+# only "||" was replaced, so `echo msg | git commit -F -` stayed one segment whose first
+# token is `echo`, and the whole pipeline skipped the guard. Order matters: "||" and "|&"
+# must be consumed before the bare "|", or each would be split into a stray half.
+for seg in cmd.replace("&&", "\n").replace("||", "\n").replace("|&", "\n").replace(";", "\n").replace("|", "\n").split("\n"):
     try:
         toks = shlex.split(seg)
     except ValueError:
@@ -67,7 +83,9 @@ for seg in cmd.replace("&&", "\n").replace(";", "\n").replace("||", "\n").split(
             repo = r
         break
 print(is_commit, repo)
-' <<<"$input" 2>/dev/null)"
+' <<<"$input" 2>/dev/null)
+  parser_or_die $?
+  read -r is_commit repo <<<"$parsed"
   [ -n "${is_commit:-}" ] || is_commit=0
   [ -n "${repo:-}" ] || repo="."
   [ -d "$repo" ] || repo="${CLAUDE_PROJECT_DIR:-$PWD}"
@@ -96,6 +114,6 @@ else
     echo "$out" >&2
     exit 2
   fi
-  echo "agent-sync guard failed to run ($code): $out" >&2
+  echo "agent-sync guard failed to run ($code): $out — diagnose with \`python3 $S check\`, or acquire a lease first: \`python3 $S acquire <TASK-ID>\`" >&2
   exit 2
 fi

package/plugins/agent-sync/hooks/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume",
+        "matcher": "startup|resume|clear",
         "hooks": [
           {
             "type": "command",

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.18.4"
+  version: "1.18.6"
   author: ssheleg
 ---
 

package/plugins/agent-sync/skills/agent-sync/scripts/agent_sync.py

@@ -33,7 +33,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.18.4"
+VERSION = "1.18.6"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")