@zalom/plastic 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/doctor.rb

@@ -1266,7 +1266,7 @@ class Doctor
 
     # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
     # e.g. an old-name copy after a rename; intent 158a AC15)
-    stray_check = stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic-manifest.json"))
+    stray_check = stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic", "manifest.json"))
     checks << stray_check if stray_check
 
     checks
@@ -1732,14 +1732,16 @@ class Doctor
               "#{tilde(File.join(plastic_home, "VERSION"))}: #{global_version}",
               "#{tilde(agent_version_path)}: #{agent_version}",
             ],
-            fixable: false
+            fixable: true,
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
           )
         end
       else
         checks << check(
           category: "core_files", name: "version_match", status: "warn",
           message: "Agent-side VERSION file not found at #{tilde(agent_version_path)}",
-          fixable: false
+          fixable: true,
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
         )
       end
     end
@@ -1944,8 +1946,7 @@ class Doctor
   # Verify, for BOTH the global manifest and the agent-side manifest, that every
   # file listed exists and its current SHA256 matches the recorded hash.
   #   - GLOBAL manifest:    <plastic_home>/manifest.json
-  #   - AGENT-side manifest: claude -> <dir>/plastic/manifest.json
-  #                          other  -> <dir>/plastic-manifest.json
+  #   - AGENT-side manifest (every agent, intent 210 D2): <dir>/plastic/manifest.json
   # Manifest format: { "version", "created", "files": { abs_path => sha256 } }.
   # A missing manifest is a fail; any missing/mismatched listed file is a fail;
   # otherwise a single pass per manifest.
@@ -1956,11 +1957,7 @@ class Doctor
     checks << verify_manifest(global_manifest, "global")
 
     agent_dir = agents[agent_key][:dir]
-    agent_manifest = if agent_key == "claude"
-                       File.join(agent_dir, "plastic", "manifest.json")
-                     else
-                       File.join(agent_dir, "plastic-manifest.json")
-                     end
+    agent_manifest = File.join(agent_dir, "plastic", "manifest.json")
     checks << verify_manifest(agent_manifest, "agent")
 
     checks
@@ -2017,6 +2014,32 @@ class Doctor
     end
   end
 
+  # install_integrity (intent 210, D4): FULL tier only, warn-only, never writes. For each
+  # installed agent, re-hash its manifest-listed files against disk and WARN on drift
+  # (a hand-edit is legitimate; this is advisory, unlike the core-tier binary manifest_sync
+  # gate). PASS when clean. `agents` here is doctor's own Hash keyed by agent key.
+  def check_install_integrity
+    checks = []
+    agents.each do |key, config|
+      manifest_path = File.join(config[:dir], "plastic", "manifest.json")
+      next unless File.exist?(manifest_path)
+      data = read_json_safe(manifest_path)
+      files = data.is_a?(Hash) ? (data["files"] || {}) : {}
+      next if files.empty?
+      drifted = files.reject { |f, h| File.exist?(f) && Digest::SHA256.file(f).hexdigest == h }
+      checks << if drifted.empty?
+        check(category: "install_integrity", name: "#{key}_integrity", status: "pass",
+              message: "#{config[:name]}: all #{files.size} tracked file(s) match the manifest")
+      else
+        check(category: "install_integrity", name: "#{key}_integrity", status: "warn",
+              message: "#{config[:name]}: #{drifted.size} tracked file(s) differ from the manifest (drift may be deliberate)",
+              details: drifted.keys.map { |f| tilde(f) }, fixable: true,
+              fix_hint: "Re-sync if unintended: npx @zalom/plastic@latest install --reinstall --#{key}")
+      end
+    end
+    checks
+  end
+
   # --- Check category 5: Project stores ---
 
   def check_project_stores
@@ -2454,6 +2477,7 @@ class Doctor
     all_checks += check_qmd
     all_checks += check_done_signals
     all_checks += check_skill_lint
+    all_checks += check_install_integrity
 
     summarize(all_checks, agent_key)
   end

package/scripts/install.rb

@@ -79,11 +79,24 @@ class Install < InstallerCore
     bootstrap if fresh
     apply_config_flags(argv)
 
-    results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
+    results = selected.map do |key|
+      result = transactional_install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall)
+      result[:key] = key
+      result
+    end
     results += already_registered.map { |key| already_registered_result(key) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
-    ledger_append(version, action)
+    # One ledger row per successfully-synced agent, carrying its harness (intent 210,
+    # G5). A run where nothing agent-specific succeeded (or selected was empty) still
+    # gets a single core-only row, so the version/action event is never silently
+    # dropped from the ledger.
+    synced = results.select { |r| r[:success] && r[:key] }
+    if synced.any?
+      synced.each { |r| ledger_append(version, action, harness: r[:key]) }
+    else
+      ledger_append(version, action)
+    end
 
     print_results(results, fresh ? :install : :reinstall)
     results
@@ -152,6 +165,8 @@ class Install < InstallerCore
       end
     end
 
+    print_agent_summary(results)
+
     installed = results.select { |r| r[:success] }
     return unless installed.any?
 
@@ -164,6 +179,21 @@ class Install < InstallerCore
     print_codex_hook_trust_reminder(installed)
   end
 
+  # Per-agent transaction summary (intent 210, D3): agent | from -> to | ok/failed.
+  # Skipped for a run with only one result, where the line above already says it all.
+  def print_agent_summary(results)
+    return if results.size <= 1
+
+    puts "\n  Agent          From \u{2192} To            Result"
+    puts "  -----          -----------      ------"
+    results.each do |r|
+      from = r[:from_version] || "-"
+      to = r[:to_version] || "-"
+      status = r[:already_registered] ? "skipped" : (r[:success] ? "ok" : "failed")
+      puts format("  %-14s %-16s %s", r[:agent], "#{from} \u{2192} #{to}", status)
+    end
+  end
+
   # Codex hooks are installed but INERT until a human reviews and trusts each
   # hook definition via /hooks (intent 198, Decision D2); Codex keys trust to
   # the hook's current command hash, so a future release that changes a hook

package/scripts/lib/installer_core.rb

@@ -133,11 +133,15 @@ class InstallerCore
   end
 
   # Append a single immutable entry. Opens in append mode; never rewrites prior lines.
-  # action ∈ { install, reinstall, update, downgrade }.
-  def ledger_append(entry_version, action)
+  # action ∈ { install, reinstall, update, downgrade }. `harness` (intent 210, G5) names
+  # which agent this row records a sync for (claude/codex/hermes); optional so a
+  # core-only or pre-210 caller still writes a valid, readable row. Readers must stay
+  # tolerant of legacy rows that carry no "harness" key at all.
+  def ledger_append(entry_version, action, harness: nil)
     FileUtils.mkdir_p(plastic_home)
-    line = JSON.generate("version" => entry_version, "action" => action, "at" => Time.now.utc.iso8601)
-    File.open(ledger_path, "a") { |f| f.puts(line) }
+    entry = { "version" => entry_version, "action" => action, "at" => Time.now.utc.iso8601 }
+    entry["harness"] = harness if harness
+    File.open(ledger_path, "a") { |f| f.puts(JSON.generate(entry)) }
   end
 
   def ledger_read
@@ -414,11 +418,20 @@ class InstallerCore
 
   # --- Agent adapters ---
 
-  def manifest_path_for(key, config)
-    case key
-    when "claude" then File.join(config[:dir], "plastic", "manifest.json")
-    else File.join(config[:dir], "plastic-manifest.json")
-    end
+  # Uniform per-agent install record dir: <agent-dir>/plastic/ holds VERSION and
+  # manifest.json for every agent (intent 210, D2). Claude already used this; Codex
+  # and Hermes are migrated onto it so one rule covers all agents and doctor's existing
+  # version_match probe (<dir>/plastic/VERSION) lands on it.
+  def record_dir_for(config)
+    File.join(config[:dir], "plastic")
+  end
+
+  def legacy_manifest_path_for(config)
+    File.join(config[:dir], "plastic-manifest.json")
+  end
+
+  def manifest_path_for(_key, config)
+    File.join(record_dir_for(config), "manifest.json")
   end
 
   def manifest_files(manifest_path)
@@ -445,6 +458,18 @@ class InstallerCore
     !manifest_files(manifest_path_for(key, config)).empty?
   end
 
+  # Agent keys whose per-agent record exists (intent 210, D2): folder-with-VERSION =
+  # registered. Reads the record, never a written config list. Fail-open: an unreadable
+  # record is simply "not installed" here (doctor reports integrity separately).
+  def installed_agents
+    agents.select { |a| File.exist?(File.join(record_dir_for(a), "VERSION")) }.map { |a| a[:key] }
+  end
+
+  def agent_version_for(config)
+    path = File.join(record_dir_for(config), "VERSION")
+    File.exist?(path) ? File.read(path).strip : nil
+  end
+
   def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
@@ -469,7 +494,12 @@ class InstallerCore
 
     # Capture the prior manifest so we can prune files that no longer ship
     # (renamed/removed skills) after a re-copy. This gives leftover-free updates.
+    # Union in the legacy flat manifest's files too (intent 210, Codex migration): an
+    # agent still on the pre-migration <dir>/plastic-manifest.json record tracked files
+    # the new per-agent manifest never lists, so without the union prune would miss them.
     old_files = manifest_files(manifest_path_for(key, config))
+    legacy_path = legacy_manifest_path_for(config)
+    old_files |= manifest_files(legacy_path) if File.exist?(legacy_path) && legacy_path != manifest_path_for(key, config)
 
     result = case key
              when "claude" then install_claude(config, force, argv: argv, input: input, reinstall: reinstall)
@@ -480,6 +510,90 @@ class InstallerCore
     new_files = manifest_files(manifest_path_for(key, config))
     pruned = prune_removed_files(old_files - new_files)
     result[:pruned] = pruned if pruned.positive?
+
+    # The legacy manifest is fully superseded once the new one is written; delete it so
+    # the migration is one-shot (intent 210, D2).
+    if File.exist?(legacy_path) && legacy_path != manifest_path_for(key, config)
+      File.delete(legacy_path)
+    end
+
+    result
+  end
+
+  # --- Per-agent transaction with auto-restore (intent 210, D3) ---
+
+  def backup_dir_for(config)
+    File.join(plastic_home, "backups", config[:key])
+  end
+
+  # Snapshot the agent's currently manifest-listed files, PLUS the manifest itself (so
+  # a restore puts the manifest and the files it describes back in sync; otherwise a
+  # restored file set would be checked against the just-written NEW manifest and fail
+  # verification all over again), into the backup dir, mirroring their absolute paths
+  # under it. Replaces any prior snapshot (one snapshot kept, D3). Returns the list of
+  # (source_abs) files snapshotted.
+  def snapshot_agent(config)
+    dir = backup_dir_for(config)
+    FileUtils.rm_rf(dir)
+    manifest_path = manifest_path_for(config[:key], config)
+    files = manifest_files(manifest_path)
+    files |= [manifest_path] if File.exist?(manifest_path)
+    files.each do |f|
+      next unless File.exist?(f)
+      dest = File.join(dir, f) # f is absolute; File.join keeps the tree distinct per agent
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(f, dest)
+    end
+    files
+  end
+
+  # Restore the snapshot back over the live tree for this agent (auto-restore, D3/D4).
+  def restore_agent(config)
+    dir = backup_dir_for(config)
+    Dir.glob(File.join(dir, "**", "*")).each do |src|
+      next unless File.file?(src)
+      dest = src.sub(dir, "")
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(src, dest)
+    end
+  end
+
+  # True when every file listed in the agent manifest exists on disk with the recorded
+  # hash. A missing or mismatched listed file is the falsifiable failure that triggers
+  # auto-restore (intent 210, G4/G8).
+  def verify_agent_manifest(config)
+    path = manifest_path_for(config[:key], config)
+    return false unless File.exist?(path)
+    data = JSON.parse(File.read(path)) rescue {}
+    files = data["files"] || {}
+    return false if files.empty?
+    files.all? { |f, h| File.exist?(f) && Digest::SHA256.file(f).hexdigest == h }
+  end
+
+  # Per-agent transaction (intent 210, D3): snapshot -> apply -> verify -> auto-restore on
+  # failure. Forward-fix: a failure here never touches other agents. On a fresh install
+  # (no prior manifest) verify-failure prunes the partial write instead of restoring.
+  def transactional_install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
+    config = agent_config(key)
+    return { agent: key, success: false, reason: "Unknown agent" } unless config
+
+    from_version = agent_version_for(config)
+    had_record = !manifest_files(manifest_path_for(key, config)).empty?
+    snapshot_agent(config) if had_record
+
+    result = install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall)
+
+    if result[:success] && !verify_agent_manifest(config)
+      if had_record
+        restore_agent(config)
+        result = { agent: config[:name], success: false, reason: "verify failed - restored prior snapshot" }
+      else
+        prune_removed_files(manifest_files(manifest_path_for(key, config)))
+        result = { agent: config[:name], success: false, reason: "verify failed - partial install pruned" }
+      end
+    end
+    result[:from_version] = from_version
+    result[:to_version] = agent_version_for(config)
     result
   end
 
@@ -559,6 +673,8 @@ class InstallerCore
   end
 
   def install_codex(config, force)
+    FileUtils.mkdir_p(record_dir_for(config))
+
     installed = []
     skills_source = File.join(package_root, "skills")
     skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
@@ -578,7 +694,13 @@ class InstallerCore
     # (stripped surgically on uninstall), same treatment as AGENTS.md.
     merge_codex_hooks(File.join(config[:home_dir], "hooks.json"))
 
-    write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
+    # Uniform per-agent record (intent 210, D2): write VERSION alongside the manifest,
+    # the same shape install_claude already writes.
+    version_file = File.join(record_dir_for(config), "VERSION")
+    File.write(version_file, "#{version}\n")
+    installed << version_file
+
+    write_manifest(installed, manifest_path_for("codex", config))
     { agent: config[:name], success: true, files: installed.size }
   end
 
@@ -723,13 +845,21 @@ class InstallerCore
   end
 
   def install_hermes(config, force)
+    FileUtils.mkdir_p(record_dir_for(config))
+
     installed = []
     skills_source = File.join(package_root, "skills")
     skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
     installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides, advisor_enabled: advisor_enabled?)
 
-    write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
+    # Uniform per-agent record (intent 210, D2): write VERSION alongside the manifest,
+    # the same shape install_claude already writes.
+    version_file = File.join(record_dir_for(config), "VERSION")
+    File.write(version_file, "#{version}\n")
+    installed << version_file
+
+    write_manifest(installed, manifest_path_for("hermes", config))
     { agent: config[:name], success: true, files: installed.size }
   end
 

package/scripts/update.rb

@@ -42,8 +42,22 @@ class Update < InstallerCore
 
     case res[:status]
     when :up_to_date
-      puts "\u{2705} Plastic v#{iv} is already up to date on the #{channel_for(iv)} channel."
-      return 0
+      targeted = target_agent_keys(argv)
+      stale = agents_needing_sync(target: iv, agent_versions: agent_versions_for(targeted))
+      if stale.empty?
+        puts "\u{2705} Plastic v#{iv} is already up to date on the #{channel_for(iv)} channel."
+        return 0
+      end
+      # Same-version repair (intent 210, D1/AC4): the core is current but a targeted
+      # agent's own record is stale or missing (e.g. a harness added after the last
+      # sync). Re-sync at the SAME version instead of the clean no-op above.
+      puts "\u{1f527} Plastic core v#{iv} is current; repairing stale agent(s): #{stale.join(", ")}"
+      exit_code = perform_switch(iv, agent_args(argv))
+      if exit_code == 0
+        announce_pending_config_asks(agent_key: primary_agent_key(argv))
+        run_post_update_doctor(full: argv.include?("--full-doctor"), synced_agents: targeted)
+      end
+      exit_code
     when :unknown_channel
       warn "No published version on the #{requested} channel."
       return 1
@@ -56,12 +70,19 @@ class Update < InstallerCore
       exit_code = perform_switch(res[:target], agent_args(argv))
       if exit_code == 0
         announce_pending_config_asks(agent_key: primary_agent_key(argv))
-        run_post_update_doctor(full: argv.include?("--full-doctor"))
+        run_post_update_doctor(full: argv.include?("--full-doctor"), synced_agents: target_agent_keys(argv))
       end
       exit_code
     end
   end
 
+  # Given the resolved target version and a { key => installed_version_or_nil } map for the
+  # agents this update targets, return the keys that still need a sync: version behind the
+  # target, or missing (nil). All-current returns []. Pure; unit-tested (intent 210, G3).
+  def agents_needing_sync(target:, agent_versions:)
+    agent_versions.select { |_k, v| v.nil? || semver_gt?(target, v) }.keys
+  end
+
   # Print any pending config question(s) straight to stdout, right after a
   # successful perform_switch (the moment the NEW config_asks.yml and
   # write-config just landed on disk via the target versions own
@@ -99,22 +120,29 @@ class Update < InstallerCore
     out.puts "  could not check config asks: #{e.message}"
   end
 
-  # Run doctor after a successful update and print a human-readable summary.
-  # Defaults to the fast core tier (agent registration + core files + manifest
-  # sync, binary pass|fail, no store walk) so a newcomer's first post-update
+  # Run doctor after a successful update and print a human-readable summary, once per
+  # synced agent (intent 210, C5: a Codex-only or --all update must not always report
+  # only claude). Defaults to the fast core tier (agent registration + core files +
+  # manifest sync, binary pass|fail, no store walk) so a newcomer's first post-update
   # run is not buried in convention warns they cannot act on. `full: true`
   # (via `--full-doctor`) runs the complete store walk instead. Informational
   # only: does not raise and does not affect the update's exit code. Accepts
-  # injected `doctor` and `out` for hermetic unit tests.
-  def run_post_update_doctor(doctor: nil, out: $stdout, full: false)
+  # injected `doctor` and `out` for hermetic unit tests. Returns the single result hash
+  # when exactly one agent was checked (matches the pre-210 return shape), else an
+  # array of per-agent result hashes.
+  def run_post_update_doctor(doctor: nil, out: $stdout, full: false, synced_agents: ["claude"])
     doctor ||= Doctor.new
+    keys = synced_agents.nil? || synced_agents.empty? ? ["claude"] : synced_agents
     out.puts full ? "\nRunning full doctor after update..." : "\nRunning core doctor after update..."
-    result = full ? doctor.run_checks("claude") : doctor.run_core_checks("claude")
-    s = result[:summary]
-    out.puts "  Doctor status: #{result[:status]} " \
-             "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
-    out.puts "  Run /plastic-doctor for details." unless result[:status] == "pass"
-    result
+    results = keys.map do |key|
+      result = full ? doctor.run_checks(key) : doctor.run_core_checks(key)
+      s = result[:summary]
+      out.puts "  [#{key}] Doctor status: #{result[:status]} " \
+               "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
+      out.puts "  Run /plastic-doctor for details." unless result[:status] == "pass"
+      result
+    end
+    keys.size == 1 ? results.first : results
   rescue StandardError => e
     # Non-blocking: a crash here (e.g. malformed file in the real store) must not
     # undo or fail an update that already succeeded. Report and move on.
@@ -152,11 +180,30 @@ class Update < InstallerCore
     nil
   end
 
-  # Agent flags to pass through to the delegated install (default --claude).
+  # Agent keys this invocation targets (intent 210, D1/G3): explicit flags in argv, or
+  # --all, or, when no flag was given at all, every currently-installed agent (never a
+  # hardcoded Claude-only default). Single source of truth for both agent_args (the
+  # argv fragment forwarded to the delegated install) and the same-version repair check.
+  def target_agent_keys(argv)
+    return agents.map { |a| a[:key] } if argv.include?("--all")
+
+    explicit = agents.select { |a| argv.include?(a[:flag]) }.map { |a| a[:key] }
+    return explicit unless explicit.empty?
+
+    installed = installed_agents
+    installed.empty? ? ["claude"] : installed
+  end
+
+  # Agent flags to pass through to the delegated install. No-flag resolves to every
+  # installed agent's flag, not a hardcoded ["--claude"] (intent 210, AC3).
   def agent_args(argv)
-    flags = agents.map { |a| a[:flag] }.select { |f| argv.include?(f) }
-    flags << "--all" if argv.include?("--all")
-    flags.empty? ? ["--claude"] : flags
+    target_agent_keys(argv).map { |k| agents.find { |a| a[:key] == k }[:flag] }
+  end
+
+  # { key => installed_version_or_nil } for the given agent keys, read from each
+  # agent's own record (intent 210, D1).
+  def agent_versions_for(keys)
+    keys.each_with_object({}) { |k, h| h[k] = agent_version_for(agent_config(k)) }
   end
 
   # The single agent key this update is installing for, for config_asks

package/skills/update/SKILL.md

@@ -47,15 +47,25 @@ first (or `npx -y @zalom/plastic@latest install --claude` directly).
 ### Step 1: Run the update
 
 ```bash
-npx -y @zalom/plastic@<channel> update --claude
+npx -y @zalom/plastic@<channel> update
 # channel switch: append --beta / --latest / --alpha
-# other agents: append --codex / --hermes / --all
+# to target a specific harness instead of every installed one: --claude / --codex / --hermes / --all
 ```
 
-`bunx -y @zalom/plastic@<channel> update --claude` works as a fallback if `npx` is
-unavailable. The command prints the transition (`vX -> vY`) or "already up to date", runs
-a post-update doctor summary, and records the move in the append-only
-`~/.plastic/versions.json` ledger.
+`bunx -y @zalom/plastic@<channel> update` works as a fallback if `npx` is unavailable.
+
+With no harness flag, `update` targets **every currently-installed harness** (read from
+each agent's own `<agent-dir>/plastic/VERSION`), never Claude alone. Pass an explicit flag
+only to target one harness specifically.
+
+If the core is already on the target version but a targeted harness's own record is stale
+or missing (for example a harness added after the last sync), `update` still re-syncs that
+harness at the same version instead of reporting a clean no-op (same-version repair).
+
+The command prints the transition (`vX -> vY`) or "already up to date", a per-agent
+transaction summary when more than one harness synced, runs a post-update doctor summary
+per synced harness, and records one `versions.json` ledger row per synced harness (each
+row's `harness` field names which one).
 
 ### Step 2: Relay any pending config question(s) the update printed
 
@@ -94,7 +104,7 @@ summary:
 
 ```
 Plastic update (<channel>)
-Command:  npx -y @zalom/plastic@<channel> update --claude <flags>
+Command:  npx -y @zalom/plastic@<channel> update <flags>
 Version:  <before> -> <after>
 Doctor:   <relayed summary, or "all clear">
 ```