agents_control 0.2.1 → 0.3.0

data/lib/agents_control/channels/telegram/router.rb

@@ -10,10 +10,27 @@ module AgentsControl
       class Router
         MAX_MESSAGE = Chunker::MAX_MESSAGE
 
+        # Long enough to walk somewhere quieter and type carefully,
+        # short enough that a challenge left unanswered doesn't sit
+        # around waiting to be replied to by accident tomorrow.
+        CHALLENGE_TTL = 300
+
         # Commands in these tabs go to a remote server, not the laptop —
         # they get a separate confirmation.
         REMOTE_COMMANDS = %w[ssh mosh].freeze
 
+        # Programs that read keystrokes as their own input, not as a
+        # line to submit to a shell. Sending a command into one of
+        # these wouldn't run it — it'd feed the letters to whatever's
+        # already there instead: pager navigation, an editor's insert
+        # mode, a REPL evaluating each character-by-character. Confirmed
+        # against a real incident: `git log`'s pager was still open,
+        # "git status" went in as keystrokes, and nothing about it ran
+        # as a command at all.
+        INTERACTIVE_COMMANDS = %w[less more most vim vi nvim emacs nano pico
+                                   man top htop irb pry python python3 node
+                                   mysql psql sqlite3].freeze
+
         # Shared list for the Telegram menu and for /help: a menu that's
         # drifted from reality is worse than no menu. The third element
         # is the argument syntax, needed only in /help; setMyCommands
@@ -35,7 +52,8 @@ module AgentsControl
         HELP = (["Commands:", ""] +
                 COMMANDS.map { |name, text, hint| "/#{name}#{hint ? " #{hint}" : ''} — #{text}" }).join("\n")
 
-        def initialize(api:, registry:, store:, config:, keyboards: nil, pending: nil, logger: nil)
+        def initialize(api:, registry:, store:, config:, keyboards: nil, pending: nil, logger: nil,
+                       passphrase: nil, inbox: nil)
           @api = api
           @registry = registry
           @store = store
@@ -43,6 +61,18 @@ module AgentsControl
           @keyboards = keyboards || Keyboards.new(store: store)
           @pending = pending
           @logger = logger
+          @passphrase = passphrase || Passphrase.new
+          @inbox = inbox
+        end
+
+        # Called once by the daemon on start; everything else here is
+        # driven by an incoming update.
+        def announce(chat_ids)
+          chat_ids.each { |chat_id| announce_passphrase(chat_id) }
+        rescue StandardError => e
+          # A notice that couldn't be sent is not a reason for the
+          # daemon to fail to come up.
+          log("couldn't send the passphrase notice: #{e.class}")
         end
 
         def handle(update)
@@ -70,10 +100,29 @@ module AgentsControl
           chat_id = message.dig("chat", "id")
           return unless allowed?(chat_id)
 
+          attachment = Inbox.attachment(message)
+          return receive(chat_id, message, attachment) if attachment
+
           text = message["text"].to_s.strip
 
           replied = message["reply_to_message"]
-          return answer_by_reply(chat_id, replied, text) if replied && !text.empty?
+          if replied && !text.empty?
+            # Checked before answer_by_reply, which would otherwise take
+            # the passphrase for something to type into a pane — and a
+            # passphrase typed into a terminal is a passphrase in the
+            # shell history.
+            challenge = @store.take(challenge_key(chat_id, replied["message_id"]))
+            return unlock(chat_id, challenge, text, message["message_id"]) if challenge
+
+            # Scoped to a reply on the wizard's own message rather than
+            # "whatever comes next": otherwise a half-finished wizard
+            # swallows the next thing typed, which could be a /run or an
+            # answer an agent is waiting on.
+            step = @store.take(wizard_key(chat_id, replied["message_id"]))
+            return wizard_entry(chat_id, step, text, message["message_id"]) if step
+
+            return answer_by_reply(chat_id, replied, text)
+          end
 
           return compose_answer(chat_id, text) if composing?(chat_id) && !text.start_with?("/")
 
@@ -119,6 +168,60 @@ module AgentsControl
           end
         end
 
+        # A file from the phone becomes a file on disk, and the agent is
+        # handed its path.
+        #
+        # A path and not a link: Telegram serves file bytes from a URL
+        # with the bot token in it, so pasting that into a pane would
+        # put the token in the terminal, in the agent's context, and in
+        # the shell history — and a leaked token is remote code
+        # execution on this machine.
+        def receive(chat_id, message, attachment)
+          path = inbox.fetch(attachment)
+          log("received #{attachment.kind}: #{File.basename(path)}")
+
+          deliver_file(chat_id, message, path)
+        rescue Inbox::TooLarge => e
+          say(chat_id, "That file is #{e.message}.")
+        rescue Api::Error, SystemCallError => e
+          say(chat_id, "Couldn't save that file: #{@api.redact(e.message)}")
+        end
+
+        # Three ways to say where it goes, in order of how explicit they
+        # are: a caption naming a tab, a reply to something already tied
+        # to a session, or neither — in which case the path is just
+        # handed back, since guessing at a target for a file is how it
+        # ends up pasted into the wrong project.
+        def deliver_file(chat_id, message, path)
+          caption = message["caption"].to_s.strip
+
+          if (target = caption[%r{\A/run\s+(\d+)}i, 1])
+            return with_session(chat_id, target) do |session|
+              execute(chat_id, session, with_path(caption.sub(%r{\A/run\s+\d+\s*}i, ""), path),
+                      show_result: !session.agent?)
+            end
+          end
+
+          replied = message["reply_to_message"]
+          remembered = replied && @store.get("reply:#{chat_id}:#{replied['message_id']}")
+          return type_into_session(chat_id, remembered, with_path(caption, path)) if remembered
+
+          say(chat_id, "Saved:\n\n`#{path}`\n\nReply to a session's message with a file to hand it " \
+                       "straight over, or caption it `/run N`.")
+        end
+
+        # Escaped, because a name like "quarterly report.csv" is
+        # entirely ordinary and an unescaped one arrives at the shell as
+        # two arguments. Shellwords leaves a path that needs nothing
+        # alone, so the common case stays readable.
+        def with_path(text, path)
+          [text, Shellwords.escape(path)].reject { |part| part.to_s.empty? }.join(" ")
+        end
+
+        def inbox
+          @inbox ||= Inbox.new(api: @api, keep_days: @config.get("telegram.inbox_keep_days", 14))
+        end
+
         def composing_key(chat_id) = "composing:#{chat_id}"
 
         def composing?(chat_id) = !@store.get(composing_key(chat_id)).nil?
@@ -196,19 +299,30 @@ module AgentsControl
 
           with_session(chat_id, number) do |session|
             next say(chat_id, "This session has no terminal — nothing to run there.") if session.terminalless?
-
-            if remote?(session)
-              confirm_remote(chat_id, session, command)
+            next confirm_remote(chat_id, session, command) if remote?(session)
+
+            # An agent isn't a shell command that finishes in a couple
+            # of seconds — it's a real task, and hooks already own
+            # telling Telegram when it's actually done or needs
+            # something. Capturing a "result" a moment after typing
+            # would just catch it mid-thought and fall back to dumping
+            # its whole transcript, which isn't a result at all — same
+            # reasoning as replying to an agent's own question
+            # (type_into_session).
+            next execute(chat_id, session, command, show_result: false) if session.agent?
+
+            next confirm_interactive(chat_id, session, command) if interactive?(session)
+
+            # One capture serves two purposes: it's checked for a
+            # pager's bare `:` prompt right here, and reused as
+            # execute()'s own "before" snapshot if it turns out clean —
+            # capturing twice would desync anything that reads the
+            # screen expecting to see it change between calls.
+            before = capture_screen(session, lines: run_result_lines)
+            if paused_for_input?(before)
+              confirm_interactive(chat_id, session, command)
             else
-              # An agent isn't a shell command that finishes in a
-              # couple of seconds — it's a real task, and hooks already
-              # own telling Telegram when it's actually done or needs
-              # something. Capturing a "result" a moment after typing
-              # would just catch it mid-thought and fall back to
-              # dumping its whole transcript, which isn't a result at
-              # all — same reasoning as replying to an agent's own
-              # question (type_into_session).
-              execute(chat_id, session, command, show_result: !session.agent?)
+              execute(chat_id, session, command, show_result: true, before: before)
             end
           end
         end
@@ -219,6 +333,21 @@ module AgentsControl
           REMOTE_COMMANDS.include?(session.foreground_command.to_s)
         end
 
+        def interactive?(session)
+          INTERACTIVE_COMMANDS.include?(session.foreground_command.to_s)
+        end
+
+        # Backstop for interactive? missing a pager by name — a custom
+        # $PAGER, or anything else not on that list. A bare `:` as the
+        # entire last line is the one thing practically every pager in
+        # the less/more lineage agrees on for "waiting on you"; a real
+        # shell prompt always has more on that line than a single
+        # colon. Takes the screen rather than the session so the
+        # caller's own capture can be reused instead of taking another.
+        def paused_for_input?(screen)
+          screen.to_s.rstrip.lines.last.to_s.strip == ":"
+        end
+
         def confirm_remote(chat_id, session, command)
           key = @store.put({ "action" => "run", "session_id" => session.id, "text" => command },
                            ttl: 300)
@@ -233,6 +362,171 @@ module AgentsControl
               markup: markup)
         end
 
+        # A tap answers "did you mean this?", which covers the thumb on
+        # the wrong line. A passphrase answers "are you you?", which is
+        # the other half — an unlocked phone in someone else's hand
+        # taps just as well as its owner does. When one is set it
+        # replaces the button for these commands rather than joining
+        # it: typing a passphrase is already a deliberate act, and two
+        # steps for one decision is how people learn to hurry through
+        # both.
+        #
+        # No passphrase set and it's the button, exactly as before.
+        def confirm_policy(chat_id, session, command, reason)
+          return challenge(chat_id, session, command, reason) if passphrase.configured?
+          return confirm_tap(chat_id, session, command, reason) unless offer_passphrase?
+
+          offer(chat_id, session, command, reason)
+        end
+
+        def offer_passphrase? = @config.get("telegram.offer_passphrase", true)
+
+        # Shown instead of a bare button the first times a destructive
+        # command turns up with no passphrase set. It still runs on one
+        # tap — refusing to would break the tool — but the offer sits
+        # next to it, at the one moment the reason for it is on screen.
+        #
+        # "Don't ask again" makes the refusal stick. Without that this
+        # is a wizard that greets someone at every `rm -rf ~` forever,
+        # which is precisely the nagging it's supposed to avoid.
+        def offer(chat_id, session, command, reason)
+          run_key = @store.put({ "action" => "run", "session_id" => session.id, "text" => command,
+                                 "vetted" => true }, ttl: 300)
+          set_key = @store.put({ "action" => "passphrase_wizard" }, ttl: 300)
+          hush_key = @store.put({ "action" => "passphrase_never" }, ttl: 300)
+
+          markup = { inline_keyboard: [
+            [{ text: "⚠️ Run anyway", callback_data: run_key }],
+            [{ text: "🔐 Set a passphrase", callback_data: set_key }],
+            [{ text: "Don't ask again", callback_data: hush_key }]
+          ] }
+
+          say(chat_id, "#{reason}\n\n`#{command}`\n\nNothing was sent. Commands like this ask for a " \
+                       "passphrase when one is set — right now there isn't one, so they ask for a tap " \
+                       "instead, and a tap is something anyone holding this phone can do.",
+              markup: markup)
+        end
+
+        def confirm_tap(chat_id, session, command, reason)
+          key = @store.put({ "action" => "run", "session_id" => session.id, "text" => command,
+                             "vetted" => true }, ttl: 300)
+
+          markup = { inline_keyboard: [[
+            { text: "⚠️ Run anyway", callback_data: key },
+            { text: "cancel", callback_data: @store.put({ "action" => "cancel" }, ttl: 300) }
+          ]] }
+
+          say(chat_id, "#{reason} — it won't go to #{session.label} without a confirmation:\n\n`#{command}`",
+              markup: markup)
+        end
+
+        def challenge(chat_id, session, command, reason)
+          sent = say(chat_id, "#{reason}\n\n`#{command}`\n\nReply to this message with the passphrase to " \
+                              "send it to #{session.label}. Anything else cancels.")
+          return unless sent
+
+          @store.put({ "session_id" => session.id, "text" => command },
+                     ttl: CHALLENGE_TTL, key: challenge_key(chat_id, sent["message_id"]))
+        end
+
+        def challenge_key(chat_id, message_id) = "unlock:#{chat_id}:#{message_id}"
+
+        def wizard_key(chat_id, message_id) = "setpass:#{chat_id}:#{message_id}"
+
+        def start_wizard(chat_id)
+          return say(chat_id, "A passphrase is already set.") if passphrase.configured?
+
+          ask_entry(chat_id, "Reply to this message with a passphrase — at least " \
+                             "#{Passphrase::MINIMUM} characters. It's deleted from the chat the moment " \
+                             "it's read, and you'll be asked to type it once more.")
+        end
+
+        def ask_entry(chat_id, prompt, sealed: nil)
+          sent = say(chat_id, prompt)
+          return unless sent
+
+          @store.put({ "sealed" => sealed }, ttl: CHALLENGE_TTL,
+                                             key: wizard_key(chat_id, sent["message_id"]))
+        end
+
+        # Both entries are deleted, and the first never waits as plain
+        # text: what's held between the two prompts is a derivation of
+        # it, which is enough to tell whether the second matches and no
+        # use for anything else.
+        def wizard_entry(chat_id, step, entry, message_id)
+          @api.delete_message(chat_id: chat_id, message_id: message_id)
+
+          return wizard_confirm(chat_id, step["sealed"], entry) if step["sealed"]
+          return ask_entry(chat_id, "That's under #{Passphrase::MINIMUM} characters. Reply with a longer one.") \
+            if entry.length < Passphrase::MINIMUM
+
+          ask_entry(chat_id, "Once more, to be sure.", sealed: Passphrase.sealed(entry))
+        end
+
+        def wizard_confirm(chat_id, sealed, entry)
+          unless Passphrase.sealed_matches?(sealed, entry)
+            return ask_entry(chat_id, "Those two didn't match. Reply with a passphrase to start over.")
+          end
+
+          save_passphrase(chat_id, entry)
+        end
+
+        # Writing to the Keychain from a background daemon isn't the
+        # same as writing from a terminal: a locked keychain can put the
+        # `security` call in front of an authorization dialog nobody is
+        # looking at, and it fails on Executor's timeout rather than
+        # succeeding. Saying so beats a silent nothing.
+        def save_passphrase(chat_id, entry)
+          passphrase.set(entry)
+          say(chat_id, "Passphrase set. Destructive commands will ask for it from now on — " \
+                       "send that command again if you still want it.\n\nSet from this chat, so it " \
+                       "guards against whoever gets to it later, not whoever has it now. " \
+                       "`agents_control passphrase set` at the machine if that matters.")
+        rescue Passphrase::TooShort => e
+          ask_entry(chat_id, "#{e.message.capitalize}. Reply with a longer one.")
+        rescue StandardError => e
+          log("couldn't save passphrase: #{e.class}")
+          say(chat_id, "Couldn't save it: #{@api.redact(e.message)}\n\n" \
+                       "Set it at the machine instead: `agents_control passphrase set`")
+        end
+
+        # The passphrase is deleted from the chat either way, and before
+        # anything else happens: whether it was right has no bearing on
+        # it not belonging in a message history that syncs to every
+        # device the account is signed in on.
+        def unlock(chat_id, challenge, attempt, message_id)
+          @api.delete_message(chat_id: chat_id, message_id: message_id)
+
+          unless passphrase.matches?(attempt)
+            log("unlock refused: session=#{challenge['session_id']}")
+            return say(chat_id, "That isn't the passphrase — nothing was sent. Send the command " \
+                                "again to retry, or run `agents_control passphrase clear` at the " \
+                                "machine if it's lost.")
+          end
+
+          session = @registry.refresh.find(challenge["session_id"])
+          return say(chat_id, "That session is already closed.") unless session
+
+          execute(chat_id, session, challenge["text"], show_result: !session.agent?, vetted: true)
+        end
+
+        def passphrase = @passphrase
+
+        def confirm_interactive(chat_id, session, command)
+          key = @store.put({ "action" => "run", "session_id" => session.id, "text" => command },
+                           ttl: 300)
+
+          markup = { inline_keyboard: [[
+            { text: "⚠️ Send anyway", callback_data: key },
+            { text: "cancel", callback_data: @store.put({ "action" => "cancel" }, ttl: 300) }
+          ]] }
+
+          say(chat_id, "#{session.label} is inside #{session.foreground_command} right now, " \
+                       "not at a shell prompt — the text would go to that, not run as a command:\n\n" \
+                       "`#{command}`",
+              markup: markup)
+        end
+
         # Enter is sent as a separate call, not tacked onto the same
         # input: a merged call can fail to send multi-line text at all.
         TYPING_PAUSE = 0.4
@@ -249,9 +543,31 @@ module AgentsControl
 
         def run_result_lines = @config.get("terminal.run_result_lines", 200)
 
-        def execute(chat_id, session, command, show_result: false)
+        # Every way text reaches a pane comes through here — /run, a
+        # reply, a file's caption, a confirmation that was taken — so
+        # this is where the guard belongs. It used to sit in `run`
+        # alone, which made it worth exactly as much as the least
+        # guarded of the other five callers: a caption reading
+        # "/run 3 rm -rf ~ #" went straight through.
+        #
+        # `vetted` is set only by the confirmations that already asked
+        # about *this* command. A tab running ssh gets its own
+        # confirmation first, and that answered a different question —
+        # "this goes to another machine", not "this destroys one" — so
+        # it doesn't count, and the guard still applies after it.
+        #
+        # Against an agent the text is a prompt rather than a command
+        # line: "look at how .env is loaded" is an ordinary thing to
+        # ask, and what the agent then tries to run is the hook path's
+        # business (Dispatcher#forbidden?).
+        def execute(chat_id, session, command, show_result: false, before: nil, vetted: false)
+          unless vetted || session.agent?
+            verdict = Policy.check(command)
+            return confirm_policy(chat_id, session, command, verdict.reason) if verdict.confirm?
+          end
+
           backend = @registry.backend_for(session)
-          before = show_result ? capture_screen(session, lines: run_result_lines) : nil
+          before ||= capture_screen(session, lines: run_result_lines) if show_result
 
           ok = backend.send_text(session.id, command, newline: false) &&
                sleep(TYPING_PAUSE).then { backend.send_text(session.id, "", newline: true) }
@@ -383,7 +699,7 @@ module AgentsControl
         end
 
         def settings_menu
-          @settings_menu ||= SettingsMenu.new(store: @store, config: @config)
+          @settings_menu ||= SettingsMenu.new(store: @store, config: @config, passphrase: passphrase)
         end
 
         def show_settings(chat_id)
@@ -425,7 +741,30 @@ module AgentsControl
           say(chat_id, "Tabs: #{sessions.size}\nAgents: #{sessions.count(&:agent?)}\n" \
                        "Backends: #{backends.empty? ? 'none' : backends}\n" \
                        "Mode: #{@config.get('answers.away', false) ? '🚶 away' : '🪑 present'}\n" \
-                       "Waiting for a reply: #{@pending ? @pending.size : 0}")
+                       "Waiting for a reply: #{@pending ? @pending.size : 0}\n" \
+                       "Destructive commands: #{passphrase.configured? ? '🔐 passphrase' : 'a tap'}")
+        end
+
+        # One message, once, and only where there's something to say.
+        # Sent from the daemon on start rather than pushed at a moment
+        # someone is deciding something else — this bot carries real
+        # interruptions (an agent stopped, a permission is needed), and
+        # spending that attention on a setting nobody has chosen yet is
+        # how people learn to dismiss the ones that matter.
+        def announce_passphrase(chat_id)
+          return if passphrase.configured? || !offer_passphrase?
+          return if @config.get("telegram.passphrase_notice_sent", false)
+
+          key = @store.put({ "action" => "passphrase_wizard" }, ttl: 86_400)
+          hush = @store.put({ "action" => "passphrase_never" }, ttl: 86_400)
+
+          say(chat_id, "🔐 No passphrase set\n\nDestructive commands from this chat — `rm -rf ~`, " \
+                       "`mkfs`, `dd` to a device, a fork bomb — ask for a tap on a button. A tap is " \
+                       "something anyone holding this phone can do.",
+              markup: { inline_keyboard: [[{ text: "🔐 Set a passphrase", callback_data: key },
+                                            { text: "Not now", callback_data: hush }]] })
+
+          @config.set("telegram.passphrase_notice_sent", true).save
         end
 
         def handle_callback(callback)
@@ -456,6 +795,8 @@ module AgentsControl
           when "transcript" then show_transcript(chat_id, payload)
           when "setting" then change_setting(chat_id, payload)
           when "menu_choice" then choose_menu_option(chat_id, payload)
+          when "passphrase_wizard" then start_wizard(chat_id)
+          when "passphrase_never" then stop_offering(chat_id)
           when "ask_question_choice" then answer_ask_user_question(chat_id, payload)
           else act_on_session(chat_id, payload)
           end
@@ -472,6 +813,12 @@ module AgentsControl
           deliver(chat_id, payload["question_id"], reply)
         end
 
+        def stop_offering(chat_id)
+          @config.set("telegram.offer_passphrase", false).save
+          say(chat_id, "Won't bring it up again. Destructive commands will keep asking for a tap, and " \
+                       "`/settings` can still turn a passphrase on later.")
+        end
+
         def start_compose(chat_id, payload)
           @store.put(payload["question_id"], ttl: 600, key: composing_key(chat_id))
           say(chat_id, "Write your reply as the next message.")
@@ -522,7 +869,8 @@ module AgentsControl
           case payload["action"]
           when "focus" then focus_session(chat_id, session)
           when "screen" then show_screen(chat_id, session)
-          when "run" then execute(chat_id, session, payload["text"], show_result: !session.agent?)
+          when "run" then execute(chat_id, session, payload["text"], show_result: !session.agent?,
+                                  vetted: payload["vetted"] ? true : false)
           when "close_confirm" then say(chat_id, "Close #{session.label}?",
                                         markup: @keyboards.confirm("close", session))
           when "close" then close_session(chat_id, session)

data/lib/agents_control/channels/telegram/settings_menu.rb

@@ -35,15 +35,17 @@ module AgentsControl
             values: [100, 200, 500, 1000], unit: "", default: 200 }
         ].freeze
 
-        def initialize(store:, config:)
+        def initialize(store:, config:, passphrase: nil)
           @store = store
           @config = config
+          @passphrase = passphrase || Passphrase.new
         end
 
         # List rows without a header — the console shows the same rows
         # in a menu navigated with arrow keys.
         def rows
-          (TOGGLES + CHOICES).map { |item| "#{item[:label]}: #{value_label(item)}" }
+          (TOGGLES + CHOICES).map { |item| "#{item[:label]}: #{value_label(item)}" } +
+            ["Destructive commands: #{@passphrase.configured? ? '🔐 passphrase' : 'a tap'}"]
         end
 
         def text
@@ -53,10 +55,18 @@ module AgentsControl
         def markup
           rows = TOGGLES.map { |item| [toggle_button(item)] }
           rows += CHOICES.map { |item| [choice_button(item)] }
+          rows << [passphrase_button] unless @passphrase.configured?
 
           { inline_keyboard: rows }
         end
 
+        # The one place the offer lives permanently, so a refusal
+        # elsewhere doesn't make it unreachable.
+        def passphrase_button
+          { text: "🔐 Set a passphrase",
+            callback_data: @store.put({ "action" => "passphrase_wizard" }, ttl: 3600) }
+        end
+
         # Apply a press and return what changed, to show the human.
         def apply(payload)
           item = find(payload["key"])

data/lib/agents_control/cli.rb

@@ -52,6 +52,11 @@ module AgentsControl
       The token is entered without echo and saved to the Keychain or
       libsecret. It's deliberately never accepted as a command-line
       argument: it would leak into `ps` and shell history.
+
+      Finally, offers to set a passphrase for destructive commands
+      (rm -rf ~, mkfs, dd to a device, a fork bomb) arriving from
+      Telegram. Optional — without one they ask for a tap on a button
+      instead.
     TEXT
     def setup
       token = ask_token
@@ -65,7 +70,9 @@ module AgentsControl
       say("Token saved: #{secrets.target.name}", :green)
       publish_commands(api)
 
-      capture_chat_id(api, me)
+      return unless capture_chat_id(api, me)
+
+      offer_passphrase
     end
 
     desc "daemon", "Run the daemon: agent hooks plus Telegram"
@@ -144,11 +151,105 @@ module AgentsControl
       end
     end
 
+    desc "passphrase SUBCOMMAND", "Passphrase for destructive commands (set/clear/status)"
+    long_desc <<~TEXT
+      A handful of commands are held back when they arrive from
+      Telegram — a recursive force delete aimed at / or $HOME, a fork
+      bomb, mkfs, dd to a raw device. Without a passphrase they come
+      back as a confirmation button. With one, they come back asking
+      for it, so an unlocked phone in someone else's hand can't tap
+      its way past them.
+
+      Entered without echo and stored derived (PBKDF2) in the Keychain
+      or libsecret. Deliberately never a command-line argument: it
+      would leak into `ps` and shell history.
+    TEXT
+    def passphrase(subcommand = "status")
+      store = Passphrase.new(secrets: secrets)
+
+      case subcommand
+      when "set" then set_passphrase(store)
+      when "clear" then clear_passphrase(store)
+      when "status" then say(store.configured? ? "Passphrase is set." : "No passphrase — a button is used instead.")
+      else say("Usage: agents_control passphrase set|clear|status", :yellow)
+      end
+    end
+
     desc "version", "Version"
     def version = say(AgentsControl::VERSION)
 
     private
 
+    # Offered at the end of setup rather than left to be found later:
+    # finishing setup is the moment the bot can start typing into this
+    # machine, and the only moment its owner is guaranteed to be
+    # reading. Skippable — a setup that can't be finished without
+    # inventing a passphrase on the spot is a setup people abandon.
+    def offer_passphrase
+      return unless $stdin.tty?
+
+      store = Passphrase.new(secrets: secrets)
+      return say("A passphrase is already set. Change it with: agents_control passphrase set") if store.configured?
+
+      say("")
+      say("Optional: a passphrase for destructive commands", :yellow)
+      say("")
+      say("A few commands are held back when they arrive from Telegram —")
+      say("`rm -rf ~`, `mkfs`, `dd` writing to a device, a fork bomb. Set a")
+      say("passphrase and you'll be asked to type it before one of those is")
+      say("sent; leave this blank and they ask for a tap on a button instead.")
+      say("")
+      say("The difference shows up when it isn't you holding the phone: a")
+      say("button taps just as easily for whoever picked it up. Typing a")
+      say("passphrase doesn't.")
+      say("")
+      say("Blank to skip — you can set one any time with:", :white)
+      say("  agents_control passphrase set", :white)
+      say("")
+
+      set_passphrase(store, skippable: true)
+    end
+
+    def set_passphrase(store, skippable: false)
+      value = ask_passphrase("Passphrase: ")
+      return skipped(skippable) if value.empty?
+
+      return say("They don't match — left unchanged.", :yellow) unless value == ask_passphrase("Again: ")
+
+      store.set(value)
+      say("Passphrase saved: #{secrets.target.name}", :green)
+    rescue Passphrase::TooShort => e
+      say("#{e.message.capitalize} — left unchanged.", :yellow)
+    rescue Passphrase::NotSaved, AgentsControl::Error => e
+      say("Couldn't save it: #{e.message}", :red)
+      say("Check `agents_control doctor` — the secret store may be locked or missing.", :white)
+    end
+
+    def skipped(skippable)
+      return say("Nothing entered — left unchanged.", :yellow) unless skippable
+
+      say("Skipped — destructive commands will ask for a tap.", :white)
+    end
+
+    def clear_passphrase(store)
+      return say("There was no passphrase set.", :yellow) unless store.configured?
+
+      store.clear
+      say("Passphrase removed — destructive commands go back to a confirmation button.", :green)
+    end
+
+    def ask_passphrase(label)
+      return $stdin.gets.to_s.chomp unless $stdin.tty?
+
+      $stderr.print(label)
+      # Same class of failures as the token prompt: ENOTTY, ENODEV, ENXIO.
+      $stdin.noecho(&:gets).to_s.chomp
+    rescue SystemCallError, IOError
+      ""
+    ensure
+      $stderr.puts if $stdin.tty?
+    end
+
     Api = Channels::Telegram::Api
     Router = Channels::Telegram::Router
     Bot = Channels::Telegram::Bot
@@ -268,6 +369,7 @@ module AgentsControl
       return say("Timed out. Run setup again.", :red) unless chat
 
       allow(chat)
+      true
     end
 
     def wait_for_message(api, seconds: 120)