rubik 0.1.0

data/lib/rubik/repl/commands/pruner.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../coeffects"
+
+module Rubik
+  module REPL
+    module Commands
+      # !prune — KÖK pencere budayıcısının kullanıcı tarafı (context-pruner
+      # planı 2026-10-09). !storage emsali: coeffect üzerinden çözer, kapalıyken
+      # dürüstçe kapalı der (knob operator-only: subagents.pruner.*).
+      # "now" zorunlu budama kuyruklar (deterministik makbuz; LLM asla
+      # bekletilmez — plan turn sınırında uygulanır), "status" durum raporu.
+      module Pruner
+        extend Base
+
+        USAGE_PRUNE = "Usage: !prune [now|status]"
+
+        def self.register(shell)
+          handler = lambda do |args, ctx|
+            harness = resolve_pruner(ctx)
+            unless harness
+              ctx.out.puts unbound_message(ctx)
+              next
+            end
+
+            sub = args.first.to_s.downcase
+            if ["status", ""].include?(sub)
+              ctx.out.puts harness.status_text
+            elsif ["now", "run", "force"].include?(sub)
+              ctx.out.puts harness.prune(reason: "user")
+            else
+              ctx.out.puts USAGE_PRUNE
+            end
+          end
+
+          shell.register_command(
+            "prune",
+            description: "Clean the ROOT conversation window via the context pruner (!prune status for details)",
+            usage: USAGE_PRUNE,
+            audience: :both,
+            &handler
+          )
+        end
+
+        def self.resolve_pruner(ctx)
+          rt = ctx.respond_to?(:runtime_manager) ? ctx.runtime_manager : nil
+          rt&.context ? Rubik::Coeffects.get(rt.context, Rubik::Coeffects::PRUNER) : nil
+        end
+
+        # Knob kapalı ile AÇIK-AMA-BAĞLANAMAMIŞ ayrımı (review 2026-10-09):
+        # ikincisi ayarı zaten açık olan operatörü sonsuz "enable et" döngüsüne
+        # sokardı — teşhis (boot warn + dmesg) adı adına söylenir.
+        def self.unbound_message(ctx)
+          knob = begin
+            ctx.config.fetch("subagents.pruner.enabled", true)
+          rescue StandardError
+            true
+          end
+          if knob == true
+            "Context pruner is ENABLED but did not bind (boot-order gap or missing supervisor — see the " \
+              "startup warning / dmesg). Fix the reported cause and restart the session."
+          else
+            "Context pruner is off (explicit opt-out). An operator can re-enable it with: " \
+              "!config set subagents.pruner.enabled true [--project|--global], then restart the session."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repl/commands/session.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../session"
+
+module Rubik
+  module REPL
+    module Commands
+      module Session
+        extend Base
+
+        # Whole-command synopsis: shared by the spine registration (usage:)
+        # and the unknown-subcommand fallback branch, so the two cannot drift.
+        USAGE_SESSION = "Usage: !session <list | resume [id] | save <name> | info | prune [days] [--apply] [--all]>"
+        PRUNE_DEFAULT_DAYS = 7
+
+        def self.register(shell)
+          shell.register_command("history", description: "List recent session history", audience: :both) do |args, ctx|
+            limit = (args.first || 20).to_i
+            hist = ctx.recorder.read_history(limit)
+            hist.each_with_index do |item, idx|
+              ctx.out.puts " #{idx + 1}: #{item['payload']}"
+            end
+          end
+
+          # Plan 91 — explicit multi-line paste mode: collects lines until a
+          # lone "." line, then dispatches the joined text as one prompt turn.
+          shell.register_command("paste", description: "Multi-line paste mode (finish with lone '.')") do |_args, ctx|
+            ctx.request_paste!
+            ctx.out.puts "[Rubik] Paste modu bir sonraki prompt'ta başlayacak."
+          end
+
+          shell.register_command("replay", description: "Replay session file") do |args, ctx|
+            path = args.first
+            replayer = ctx.session_replayer
+            if replayer.replay_file(path)
+              ctx.out.puts "Replay completed."
+            else
+              ctx.out.puts "Session file not found: #{path}"
+            end
+          end
+
+          shell.register_command("session", description: "Manage recorded sessions (list|resume|info|prune)",
+                                            usage: USAGE_SESSION) do |args, ctx|
+            sub = args.first&.downcase || "list"
+            root_d = ctx.buffer_manager&.root_dir || Dir.pwd
+            home_d = ctx.config&.home_dir || ENV.fetch("HOME", nil)
+
+            case sub
+            when "list"
+              sessions = Rubik::Session::Manager.list_sessions(root_d, home_d, config: ctx.config)
+              if sessions.empty?
+                ctx.out.puts "No recorded sessions found for this workspace."
+              else
+                ctx.out.puts "=== Recorded Sessions (#{sessions.size}) ==="
+                sessions.each_with_index do |s, idx|
+                  mark = s[:path] == ctx.recorder.session_file ? " [CURRENT]" : ""
+                  ctx.out.puts "  #{idx + 1}. #{s[:id]} (#{s[:scope]}) - #{s[:event_count]} events - Last: \"#{s[:last_prompt]}\"#{mark}"
+                end
+              end
+            when "resume", "continue", "load"
+              target_id = args[1]
+              if target_id.nil?
+                picked = interactive_session_pick(ctx)
+                if picked == :picker_cancelled
+                  ctx.out.puts "[Rubik::Session] Resume iptal edildi."
+                  next
+                end
+                target_id = picked || :latest
+              end
+              res = ctx.resume_session(target_id)
+              ctx.out.puts "Resume failed: #{res[:error]}" unless res[:ok]
+            when "info"
+              ctx.out.puts "Active Session File: #{ctx.recorder.session_file}"
+              ctx.out.puts "Total Events in Session: #{ctx.recorder.events.size}"
+            when "prune", "clean", "cleanup"
+              run_prune(args.drop(1), ctx)
+            when "save"
+              target_name = args[1]
+              if target_name.nil? || target_name.strip.empty?
+                ctx.out.puts "Usage: !session save <name>"
+              else
+                safe_name = File.basename(target_name.strip.sub(/\.jsonl$/, ""))
+                if safe_name.empty? || safe_name.start_with?(".")
+                  ctx.out.puts "Error: Invalid session name '#{target_name}'."
+                  next
+                end
+
+                target_dir = File.join(root_d, ".rubik", "sessions")
+                FileUtils.mkdir_p(target_dir)
+                target_file = File.join(target_dir, "#{safe_name}.jsonl")
+
+                if ctx.recorder.session_file && File.exist?(ctx.recorder.session_file)
+                  FileUtils.cp(ctx.recorder.session_file, target_file)
+                else
+                  File.open(target_file, "w") do |f|
+                    ctx.recorder.events.each { |ev| f.puts(JSON.dump(ev)) }
+                  end
+                end
+                ctx.recorder.switch_session_file(target_file, cleanup_empty_current: false)
+                ctx.out.puts "[Rubik::Session] Session saved to #{target_file}"
+              end
+            else
+              ctx.out.puts USAGE_SESSION
+            end
+          end
+        end
+
+        # Interactive session picker (Antigravity /resume style): arrow-key
+        # selection over recorded sessions on capable TTYs. Returns the
+        # session id, :picker_cancelled on Ctrl+C (caller aborts the
+        # resume), or nil in pipes/tests so `resume` falls back to :latest.
+        class << self
+          # `!session prune [days] [--apply] [--all]` — dry-run by default:
+          # prints the blast radius of files that WOULD be deleted and only
+          # unlinks once the operator passes --apply. The active session file
+          # is always protected. `--all` widens scope to ~/.rubik/sessions.
+          def run_prune(rest, ctx)
+            apply = rest.any? { |a| ["--apply", "--yes", "-y", "apply", "delete"].include?(a.downcase) }
+            include_global = rest.any? { |a| ["--all", "-a", "all", "global"].include?(a.downcase) }
+            day_arg = rest.find { |a| a =~ /\A\d+(\.\d+)?\z/ }
+            days = day_arg ? day_arg.to_f : PRUNE_DEFAULT_DAYS
+            days = PRUNE_DEFAULT_DAYS unless days.positive?
+
+            root_d = ctx.buffer_manager&.root_dir || Dir.pwd
+            home_d = ctx.config&.home_dir || ENV.fetch("HOME", nil)
+            active = ctx.recorder&.session_file
+
+            report = Rubik::Session::Manager.prune_sessions(
+              days: days, root_dir: root_d, home_dir: home_d,
+              exclude_file: active, apply: apply, include_global: include_global, config: ctx.config
+            )
+
+            scope_label = include_global ? "project + global" : "project"
+            size_mb = report[:bytes] / 1_048_576.0
+
+            if report[:candidates].zero?
+              ctx.out.puts "[Rubik::Session] No #{scope_label} sessions older than #{format_days(days)} to prune."
+              return
+            end
+
+            verb = apply ? "Deleted" : "Would delete"
+            ctx.out.puts "[Rubik::Session] #{verb} #{report[:candidates]} #{scope_label} session(s) " \
+                         "older than #{format_days(days)} (#{format('%.1f', size_mb)} MB)."
+            unless report[:sample].empty?
+              ctx.out.puts "  e.g. #{report[:sample].join(', ')}#{', …' if report[:candidates] > report[:sample].size}"
+            end
+            ctx.out.puts "  [CURRENT] active session protected: #{File.basename(active.to_s)}" if report[:protected_skipped].positive?
+
+            ctx.out.puts "  Dry run — nothing removed. Re-run with '--apply' to delete." unless apply
+          end
+
+          def format_days(days)
+            days == days.to_i ? "#{days.to_i}d" : "#{days.round(1)}d"
+          end
+
+          def interactive_session_pick(ctx)
+            return nil unless Rubik::UI::Capability.interactive?(input: ctx.input, output: ctx.output)
+
+            root_d = ctx.buffer_manager&.root_dir || Dir.pwd
+            home_d = ctx.config&.home_dir || ENV.fetch("HOME", nil)
+            sessions = Rubik::Session::Manager.list_sessions(root_d, home_d, config: ctx.config)
+            return nil if sessions.empty?
+
+            prompt = Rubik::UI::Approvals.build_prompt(ctx)
+            prompt.select("Devam edilecek oturumu seç:") do |menu|
+              sessions.first(15).each do |s|
+                menu.choice "#{s[:id]} · #{s[:event_count]} olay · \"#{s[:last_prompt].to_s[0, 40]}\"", s[:id]
+              end
+              menu.choice "← en son oturum (:latest)", :latest
+            end
+          rescue Interrupt
+            Rubik::REPL::InterruptHandler.restore_console_after_interrupt
+            :picker_cancelled
+          rescue StandardError => e
+            Rubik::Log.warn(:repl, "session picker failed (#{e.class}: #{e.message}); resume selection skipped")
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repl/commands/skills.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Rubik
+  module REPL
+    module Commands
+      module Skills
+        # Whole-command synopsis: shared by the spine registration (usage:)
+        # and the unknown-subcommand fallback branch, so the two cannot drift.
+        USAGE_SKILL = "Usage: !skill [list|show <name>|info <name>|reload]"
+
+        def self.register(shell)
+          handler = proc do |args, ctx|
+            manager = ctx.skill_manager
+            unless manager
+              ctx.out.puts "Skill manager is not initialized."
+              next
+            end
+
+            args = args.split if args.is_a?(String)
+            subcommand = args[0] || "list"
+
+            case subcommand
+            when "list"   then list_skills(ctx, manager)
+            when "show"   then show_skill(ctx, manager, args[1])
+            when "info"   then info_skill(ctx, manager, args[1])
+            when "reload" then reload_skills(ctx, manager)
+            else
+              ctx.out.puts "Unknown subcommand: #{subcommand}. #{USAGE_SKILL}"
+            end
+          end
+
+          shell.register_command("skill", description: "Agent skills (agentskills.io): list, show <name>, info <name>, reload",
+                                          usage: USAGE_SKILL, audience: :both, &handler)
+          shell.register_command("skills", description: "List discovered agent skills", usage: USAGE_SKILL, audience: :human) do |_args, ctx|
+            handler.call(["list"], ctx)
+          end
+        end
+
+        def self.list_skills(ctx, manager)
+          summary = manager.status_summary
+          skills = manager.all
+          ctx.out.puts "🧠 Agent Skills — #{skills.size} active (#{summary[:skipped]} skipped, #{summary[:notes]} notes)"
+          if skills.empty?
+            ctx.out.puts "No skills discovered. Add .rubik/skills/<name>/SKILL.md (project), " \
+                         "~/.rubik/skills/<name>/SKILL.md (user), or extend the skills.paths config."
+          else
+            skills.each do |skill|
+              desc = skill.description.length > 72 ? "#{skill.description[0, 69]}..." : skill.description
+              ctx.out.puts format("  %<name>-24s [%<scope>-7s] %<desc>s", name: skill.name, scope: skill.scope, desc: desc)
+            end
+          end
+          print_shadowed(ctx, summary[:shadowed])
+          print_issues(ctx, manager)
+        end
+
+        def self.show_skill(ctx, manager, name)
+          skill = manager.find(name.to_s)
+          return ctx.out.puts "Unknown skill '#{name}'. Use '!skill list'." unless skill
+
+          ctx.out.puts Rubik::Platform.read_text(skill.path)
+        rescue StandardError => e
+          ctx.out.puts "Error reading skill '#{name}': #{e.message}"
+        end
+
+        def self.info_skill(ctx, manager, name)
+          skill = manager.find(name.to_s)
+          return ctx.out.puts "Unknown skill '#{name}'. Use '!skill list'." unless skill
+
+          ctx.out.puts "=== Skill '#{skill.name}' ==="
+          ctx.out.puts "  Scope         : #{skill.scope}"
+          ctx.out.puts "  Directory     : #{skill.root}"
+          ctx.out.puts "  Description   : #{skill.description}"
+          ctx.out.puts "  License       : #{skill.license || '-'}"
+          ctx.out.puts "  Compatibility : #{skill.compatibility || '-'}"
+          allowed = skill.allowed_tools.empty? ? "-" : "#{skill.allowed_tools.join(' ')} (advisory, not enforced)"
+          ctx.out.puts "  Allowed tools : #{allowed}"
+          meta = skill.metadata.empty? ? "-" : skill.metadata.map { |k, v| "#{k}=#{v}" }.join(", ")
+          ctx.out.puts "  Metadata      : #{meta}"
+          aux = skill.auxiliary_files
+          resources = aux.empty? ? "none" : aux.map { |dir, files| "#{dir}/ (#{files.size})" }.join(", ")
+          ctx.out.puts "  Resources     : #{resources}"
+          skill.warnings.each { |warning| ctx.out.puts "  ⚠ #{warning.field} #{warning.message}" }
+        end
+
+        def self.reload_skills(ctx, manager)
+          manager.reload!
+          summary = manager.status_summary
+          scopes = summary[:by_scope].map { |scope, count| "#{scope}: #{count}" }.join(", ")
+          ctx.out.puts "🔄 Skills reloaded: #{summary[:total]} active (#{scopes.empty? ? 'none' : scopes}), " \
+                       "#{summary[:skipped]} skipped, #{summary[:notes]} notes."
+          print_shadowed(ctx, summary[:shadowed])
+          print_issues(ctx, manager)
+        end
+
+        def self.print_shadowed(ctx, shadowed)
+          shadowed.each do |name, entry|
+            losers = entry[:loser_scopes].join(", ")
+            ctx.out.puts "  ⇢ '#{name}' shadowed: #{losers} copy ignored (winner: #{entry[:winner_scope]})"
+          end
+        end
+
+        def self.print_issues(ctx, manager)
+          manager.issues.each do |issue|
+            mark = issue.error? ? "⚠" : "·"
+            ctx.out.puts "  #{mark} #{File.basename(issue.path)}: #{issue.field} #{issue.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repl/commands/storage.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../coeffects"
+
+module Rubik
+  module REPL
+    module Commands
+      # !storage — merkezi rubik://storage FS-DB'ye kullanıcı tarafı bakış
+      # (storage-show-surface planı B): "raporu göster" isteğini modeli tamamen
+      # devre dışı bırakarak karşılar. Depo araç-eylemlerinin aksine bu komut
+      # sadece OKUR — yazma düzlemi storage aracında kalır.
+      module Storage
+        extend Base
+
+        USAGE_STORAGE = "Usage: !storage [<type|id|type.row|row|hash-prefix|ref>] [refs]"
+
+        def self.register(shell)
+          handler = lambda do |args, ctx|
+            store = resolve_store(ctx)
+            unless store
+              ctx.out.puts "Central storage is not available in this runtime (config storage.enabled=false or standalone construction)."
+              return
+            end
+
+            dispatch(args, ctx, store)
+          end
+
+          shell.register_command(
+            "storage",
+            description: "Browse the central rubik://storage database (entities and refs)",
+            usage: USAGE_STORAGE,
+            audience: :both,
+            &handler
+          )
+        end
+
+        def self.dispatch(args, ctx, store)
+          return render_refs_table(ctx, store) if args.include?("refs")
+          return ctx.out.print(Rubik::Storage::Render.project(store.project, store.project_summary)) if args.empty?
+
+          selector = args.first.to_s
+          return render_type_listing(ctx, store, selector.downcase) if Rubik::Storage::Store::TYPES.include?(selector.downcase)
+
+          record = resolve_any(store, selector)
+          if record
+            ctx.out.print(Rubik::Storage::Render.card(record, project: store.project, refs: store.refs))
+          else
+            ctx.out.puts "Storage entity not found: '#{selector}' in project '#{store.project}'. " \
+                         "Try '!storage' for counts, '!storage refs' for aliases, or '!storage <type>' for a listing."
+          end
+        end
+
+        # Store#get tip ister; kullanıcı seçicisi tipsiz gelir — tüm tiplerde
+        # çöz (tam id → type.row → row → hash öneki → alias zinciri meta
+        # referanslı olduğu için yalnız eşleşen tipin kayıtlarında tutarlı).
+        def self.resolve_any(store, selector)
+          Rubik::Storage::Store::TYPES.lazy.map { |t| store.get(type: t, id: selector) }.find(&:itself)
+        end
+
+        def self.render_type_listing(ctx, store, type)
+          summaries = store.list(type: type).map(&:to_h)
+          ctx.out.print(Rubik::Storage::Render.listing(project: store.project, type: type,
+                                                       summaries: summaries, refs: store.refs))
+        end
+
+        def self.render_refs_table(ctx, store)
+          refs = store.refs
+          if refs.empty?
+            ctx.out.puts "No refs defined in project '#{store.project}'."
+            return
+          end
+
+          ctx.out.puts "Refs in '#{store.project}':"
+          refs.sort.each { |name, id| ctx.out.puts "  #{name} → #{id}" }
+        end
+
+        def self.resolve_store(ctx)
+          rt = ctx.respond_to?(:runtime_manager) ? ctx.runtime_manager : nil
+          rt&.context ? Rubik::Coeffects.get(rt.context, Rubik::Coeffects::STORAGE_STORE) : nil
+        end
+      end
+    end
+  end
+end

data/lib/rubik/repl/commands/subagents.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../orchestrator/subagent/budget"
+require_relative "../../orchestrator/subagent/notices"
+
+module Rubik
+  module REPL
+    module Commands
+      # REPL bang command (!subagents) for monitoring and supervising autonomous
+      # subagents (Plan 94 - Linux Init PID 1 Supervisor Model).
+      module Subagents
+        extend Base
+
+        # Whole-command synopsis: shared by the spine registration (usage:)
+        # and the unknown-subcommand fallback branch, so the two cannot drift.
+        USAGE_SUBAGENTS = "Usage: !subagents [list | status <id> | wait [id] [sec] | extend <id> [steps] | resume [id] | reuse <id> <prompt> | clean | kill <id> | kill-all]"
+
+        def self.register(shell)
+          handler = lambda do |args, ctx|
+            subcmd = args.first&.downcase
+            sup = resolve_supervisor(ctx)
+
+            unless sup
+              ctx.out.puts "SubagentSupervisor is not available."
+              return
+            end
+
+            case subcmd
+            when nil, "list" then render_list(ctx, sup)
+            when "status" then render_status(ctx, sup, args[1])
+            when "types" then render_types(ctx, sup)
+            when "extend", "grant", "steps" then handle_extend(ctx, sup, args[1], args[2])
+            when "resume", "retry" then handle_resume(ctx, sup, args[1])
+            when "reuse", "redeploy" then handle_reuse(ctx, sup, args[1], args[2..])
+            when "clean", "reap" then handle_clean(ctx, sup)
+            when "wait" then handle_wait(ctx, sup, args[1], args[2])
+            when "kill" then handle_kill(ctx, sup, args[1])
+            when "kill-all", "killall"
+              sup.kill_all
+              ctx.out.puts "All subagents terminated."
+            else
+              ctx.out.puts "Unknown !subagents subcommand: '#{subcmd}'. #{USAGE_SUBAGENTS}"
+            end
+          end
+
+          description = "Supervise and manage autonomous subagents (list, status, types, extend, resume, kill, kill-all)"
+          shell.register_command("subagents", description: description, usage: USAGE_SUBAGENTS, audience: :both, &handler)
+          shell.register_command("subagent", description: "Alias for !subagents", usage: USAGE_SUBAGENTS, audience: :both, &handler)
+          # NB: no "agents" alias — System owns !agents (the interactive
+          # agent/fiber board); a second registration here would silently
+          # overwrite it (register_command only refuses custom-over-builtin).
+        end
+
+        def self.resolve_supervisor(ctx) = ctx.subagent_supervisor
+
+        def self.render_list(ctx, sup)
+          instances = sup.list
+          if instances.empty?
+            ctx.out.puts "No subagents currently running or tracked."
+            return
+          end
+
+          ctx.out.puts "=== Subagent Process Hierarchy (#{instances.size} tracked, #{sup.active_count} active) ==="
+          instances.each do |inst|
+            dur = if inst.running?
+                    "up #{inst.uptime.round(1)}s"
+                  elsif inst.state == :queued
+                    "queued (waiting on: #{inst.depends_on.join(', ')})"
+                  else
+                    "ended (#{inst.uptime.round(1)}s)"
+                  end
+            ctx.out.puts "  • [#{inst.id}] #{inst.state.to_s.upcase} (role: #{inst.role}, type: #{inst.type_name}, #{dur})"
+          end
+        end
+
+        def self.render_status(ctx, sup, id)
+          if id.to_s.strip.empty?
+            ctx.out.puts "Usage: !subagents status <subagent_id>"
+            return
+          end
+
+          inst = sup.get(id)
+          unless inst
+            ctx.out.puts "Subagent '#{id}' not found."
+            return
+          end
+
+          ctx.out.puts "Subagent: #{inst.id} (Parent: #{inst.parent_id})"
+          ctx.out.puts "  Role:        #{inst.role}"
+          ctx.out.puts "  Type:        #{inst.type_name}"
+          ctx.out.puts "  State:       #{inst.state.to_s.upcase}"
+          ctx.out.puts "  Steps:       #{inst.current_step}/#{inst.max_steps}"
+          ctx.out.puts "  Uptime:      #{inst.uptime.round(2)}s"
+          ctx.out.puts "  Workspace:   #{inst.workspace}"
+          ctx.out.puts "  Transcript:  #{inst.transcript_uri}"
+          ctx.out.puts "  Last Error:  #{inst.last_error}" if inst.last_error
+          ctx.out.puts "  Result:      #{inst.result.to_s.slice(0, 150)}..." if inst.result
+        end
+
+        def self.render_types(ctx, sup)
+          types = sup.type_registry.list
+          ctx.out.puts "=== Available Subagent Archetypes (#{types.size}) ==="
+          types.each do |t|
+            flags = []
+            flags << "write" if t.enable_write_tools
+            flags << "nesting" if t.enable_subagent_tools
+            flag_str = flags.empty? ? "read-only" : flags.join(", ")
+            ctx.out.puts "  • #{t.name.ljust(12)} [#{flag_str}]: #{t.description}"
+          end
+        end
+
+        def self.handle_kill(ctx, sup, id)
+          if id.to_s.strip.empty?
+            ctx.out.puts "Usage: !subagents kill <subagent_id>"
+            return
+          end
+
+          if sup.kill(id)
+            ctx.out.puts "Subagent '#{id}' and child tree killed."
+          else
+            ctx.out.puts "Subagent '#{id}' not found."
+          end
+        end
+
+        def self.handle_extend(ctx, sup, id, steps_arg)
+          if id.to_s.strip.empty?
+            ctx.out.puts "Usage: !subagents extend <subagent_id> [additional_steps]"
+            return
+          end
+
+          steps = Rubik::Orchestrator::Subagent::Budget.normalize_grant(steps_arg)
+          if sup.extend_budget(id, steps)
+            inst = sup.get(id)
+            ctx.out.puts "Extended budget for #{id} by #{steps} steps (total: #{inst.max_steps}, state: #{inst.state.to_s.upcase})."
+          else
+            ctx.out.puts "Could not extend budget for #{id} (not found or inactive)."
+          end
+        end
+
+        def self.handle_resume(ctx, sup, id)
+          if id.to_s.strip.empty?
+            resumed = sup.resume_all
+            return ctx.out.puts "No paused subagents to resume." if resumed.empty?
+
+            ctx.out.puts "Resumed #{resumed.size} subagent(s): #{resumed.join(', ')}."
+          elsif sup.resume(id)
+            inst = sup.get(id)
+            ctx.out.puts "Resumed subagent '#{id}' (state: #{inst.state.to_s.upcase})."
+          else
+            ctx.out.puts "Could not resume subagent '#{id}' (not found or not in pausable state)."
+          end
+        end
+
+        # Context-preserving reuse of a finished subagent (maestro persona).
+        def self.handle_reuse(ctx, sup, id, words)
+          prompt = Array(words).join(" ").strip
+          return ctx.out.puts "Usage: !subagents reuse <subagent_id> <new task prompt>" if id.to_s.strip.empty? || prompt.empty?
+
+          begin
+            inst = sup.redeploy(id, prompt: prompt)
+            ctx.out.puts "Redeployed '#{id}' with a new task — context preserved (state: #{inst.state.to_s.upcase})."
+          rescue ArgumentError => e
+            ctx.out.puts e.message
+          end
+        end
+
+        def self.handle_clean(ctx, sup)
+          reaped = sup.reap_finished!(force: true)
+          return ctx.out.puts "No finished subagents to reap." if reaped.empty?
+
+          ctx.out.puts "Reaped #{reaped.size} finished subagent(s): #{reaped.join(', ')} (transcripts persist)."
+        end
+
+        def self.handle_wait(ctx, sup, arg1, arg2)
+          ids = nil
+          timeout = Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT
+          if arg1 =~ /^\d+$/
+            timeout = arg1.to_i
+          elsif arg1 && !arg1.empty?
+            ids = [arg1]
+            timeout = arg2.to_i if arg2 =~ /^\d+$/
+          end
+
+          ctx.out.puts "Waiting for subagents (timeout: #{timeout}s)..."
+          results = sup.wait_for(ids, timeout: timeout)
+          return ctx.out.puts "No active subagents tracked." if results.empty?
+
+          ctx.out.puts "=== Subagents Wait Finished (#{results.size}) ==="
+          results.each { |r| ctx.out.puts "  • #{r[:id].ljust(12)} [#{r[:state].to_s.upcase}]: #{r[:role]}" }
+        end
+      end
+    end
+  end
+end