samagotchi 0.118.0 → 0.119.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06322a414267628aff61367b71dc4a6ecb76d4789673d594aff987a8da678d94
-  data.tar.gz: 12cc40d770cfd7072ccb1a64543033da5619f19d472ae69e7db880ae9a7f867f
+  metadata.gz: 67772cbed2c590109f257a85de25cc009250b6fb3a78c1bf4e1b2194561846b7
+  data.tar.gz: ac023d3b8f28c1196b234e528eae9faf9947181ee6f44111c7f00723eb92b196
 SHA512:
-  metadata.gz: 0db2e221e335c74dcb3770ec17d92a2ded1b4e92589e958e33f95008e0ab5a9e13d72aed2ebb3bc2875fa6800e5cba6e19898b68515fda951a1709b5fc864a09
-  data.tar.gz: 7d8e40e0f7966a75d0914229a6e7a94b626ed9a045451ab65c154eef2eea3a5e8ba81eb20fc90cff703986e063fbfbef55225919a4be47e92b3b6b28ae611bbf
+  metadata.gz: e818ad092946ec8ca8d1765079824a0cd7f540734fc9ad52b1a28d2ad70f12be7ff21324f348eda1461474d2924e99f97fa5f45fe25e11e16cc65c7e2a7f63af
+  data.tar.gz: 2c852f4b48dcee1bd4c742eb3acdbe34ee802a53407b562b09398b13be34a9de3bcbdeebb058781691c07a7c696797ea660133e84155ccb2247ab6e9e5f72596

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.119.0] - 2026-10-26
+
+### Added
+
+- claude-peer (0.4.3): `pair --inbox-socket PATH` pairs both ways with chi on
+  another machine through an `ssh -R` forward of Claude's socket
+  ([docs/plugins.md](docs/plugins.md)); docs/cli.md: remote sessions through an
+  SSH tunnel. Update with `chi update`.
+
 ## [0.118.0] - 2026-10-26
 
 ### Changed
@@ -4445,7 +4454,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.118.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.119.0...HEAD
+[0.119.0]: https://github.com/dm1try/samagotchi/compare/v0.118.0...v0.119.0
 [0.118.0]: https://github.com/dm1try/samagotchi/compare/v0.117.0...v0.118.0
 [0.117.0]: https://github.com/dm1try/samagotchi/compare/v0.116.0...v0.117.0
 [0.116.0]: https://github.com/dm1try/samagotchi/compare/v0.115.0...v0.116.0

data/docs/cli.md

@@ -1336,6 +1336,35 @@ chi --remote studio --dir /Users/me/app -p "hi"        # a new session there (--
   has installed (`chi --remote studio sessions restart ab12`), this terminal
   older than studio (`chi update` here).
 
+#### Through an SSH tunnel
+
+When that machine's chi web is only reachable over SSH — behind a sign-in proxy
+(`chi --remote` through one isn't supported yet), or bound to 127.0.0.1 —
+forward its port and add it as a remote like any other:
+
+```sh
+ssh -N -L 14567:127.0.0.1:4567 studio          # the host's web.port, 4567 by default
+chi remote add work http://127.0.0.1:14567 --token-file work-token
+# work-token: the host's $XDG_STATE_HOME/samagotchi/web-token
+chi --remote work sessions list
+```
+
+- Pick a local port other than 14567 when this machine runs its own chi web.
+- Forward only chi web's port, never a worker's: a session's Bridge is
+  unauthenticated.
+- Without `web.public_url` there, a request that arrives through the tunnel
+  looks local and needs no token, so any process here reaching the forwarded
+  port acts as you there. With it set, every request needs the token, which
+  `chi --remote` sends as Bearer.
+- `-L` binds 127.0.0.1 unless you write `-g` or `0.0.0.0:`: don't.
+- Attaching works through the tunnel too (`chi --remote work --attach ab12`),
+  plain http, no proxy.
+
+SSH can forward a Unix socket as well, which is how claude-peer's pairing makes
+a Claude session on this laptop reachable from chi on that machine
+(`pair --inbox-socket <path>`): see [plugins.md](plugins.md), "chi on another
+machine".
+
 How it works inside (`SessionAccess`, chi web's routes, where each check runs):
 [internals/remote-sessions.md](internals/remote-sessions.md).
 

data/docs/configuration.md

@@ -1659,6 +1659,8 @@ What changes once `web.public_url` is set:
   `X-Forwarded-For` or `Forwarded` (403 `proxied`). That is a heuristic, not a lock: a forward that adds no such header
   (nginx's `proxy_pass` with its defaults, a plain TCP forward) still reaches a worker, as the owner.
 - `chi --remote` to a chi web behind a sign-in proxy isn't supported yet.
+  SSH to that machine works instead: forward its port and add it as a remote
+  ([Through an SSH tunnel](cli.md#through-an-ssh-tunnel)).
 
 > **Warning.** Until Bridges get a secret of their own (planned), don't run chi web behind a proxy or tunnel that can
 > reach any local port, such as a pod forwarding every `https://<port>.<pod>…`, unless it adds `X-Forwarded-For` or

data/docs/plugins.md

@@ -2249,6 +2249,26 @@ Claude pairs; without one the bundle costs one tool declaration.
   them (or ask it to run `chi --remote studio send --wait <id>`). A session
   that already has a `claude-inbox` it can't reach:
   `chi --remote studio context rm claude-inbox <id>`.
+  **Two ways to make it two-way over SSH.** SSH can forward a Unix socket, so
+  the inbox leg works too. On the laptop:
+
+  ```sh
+  ssh studio rm -f /tmp/claude-peer-ab12.sock
+  ssh -N -o ExitOnForwardFailure=yes -R /tmp/claude-peer-ab12.sock:"$CLAUDE_CODE_MESSAGING_SOCKET" studio
+  ```
+
+  the second running in the background while chi may send (the `rm -f` first:
+  a remote forward's stale socket is replaced only when the **server's** sshd
+  has `StreamLocalBindUnlink yes`). Then
+  `CHI_REMOTE=studio sh <bundle>/scripts/pair --inbox-socket /tmp/claude-peer-ab12.sock ab12`
+  attaches both sources, with `claude-inbox`'s hint that path on the Studio. A
+  re-pair this way replaces an outbox-only pairing's `claude-outbox` and its
+  why. Claude's socket changes when that Claude session restarts: stop the ssh,
+  run both lines, pair again. A path chi quotes (a `payload:` file, a diff to
+  check) is on the Studio, not the laptop. Whoever can write to that socket on
+  the remote machine can send into this Claude session (sshd makes it the
+  user's, mode 0600 by default): fine on your own machine or pod, not a shared
+  host. Claude's own skill has the same under "chi on another machine over SSH".
 - **Asking first.** The tool has no `targets:`, so guardrails match it by name
   only: to be asked before each send, add a rule ([Rules in
   config.yml](guardrails.md#rules-in-configyml)):
@@ -2353,6 +2373,8 @@ skill install card) works the same.
   <bundle>/scripts/pair <id>` (or `--remote NAME` in `CHI`) pairs through
   the Studio's chi web, and only the outbox leg works: `codex_send` runs
   `codex queue` on the machine chi runs on, where this Codex's thread isn't.
+  Claude's `--inbox-socket` trick doesn't apply here: `codex-inbox`'s hint is a
+  thread id, not a socket, so there is nothing to forward through SSH.
   So `pair` attaches only `codex-outbox` and prints one line saying chi there
   can't send to this Codex. Through a remote chi talks HTTP, not files, so
   `writable_roots` doesn't matter; Codex's sandbox may block the network

data/lib/samagotchi/bundles/claude-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: claude-peer
-version: 0.4.2
+version: 0.4.3
 scope: system
 description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-outbox context; /claude install-skill installs Claude's chi-peer skill, which pairs"
 trust_level: reviewed
@@ -12,8 +12,8 @@ plugin:
   file: plugin.rb
   sha256: sha256:50f427d3862ae9d0d15693b4d887c528162b96c0320cc663df89d59d830d4660
 scripts:
-  pair: sha256:2e66103c43fce5eab05f897682ba943f394743c1ad47bf439be3ce529f1b2058
-  chi-peer-SKILL.md: sha256:e991a91139a127a60f9a216043eb5864945fb211952a1e3c8db2068c6cc254f1
+  pair: sha256:bd850e8091098e249ac5b9b04a95a4d8a0dd8501cf9d58639a47d4f3bce1d757
+  chi-peer-SKILL.md: sha256:b9366f8f4aee9c54d209368ce421eab7b971c03c75efab0415d1988fd40f9e60
 # The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
 # An agreeing answer's closing wake (the skills say an OK wakes chi once)
 # and the plugin's OUTBOX (Plugin::Peer's rename of REVIEW) need chi 0.70.0.

data/lib/samagotchi/bundles/claude-peer/scripts/chi-peer-SKILL.md

@@ -89,6 +89,54 @@ EOF
 - Never answer a chi message with `chi send`: it counts as the user typing,
   outside the round's limit. Use it only when the user asks you to.
 
+## chi on another machine over SSH
+
+When the chi session runs on a machine this Claude session reaches with SSH
+(the user says so, or `CHI_REMOTE` or a remote URL is in play) and chi should
+send here too, pair with `--inbox-socket`: the socket chi writes to is then one
+on chi's machine, an `ssh -R` forward of this session's socket.
+
+You need a chi remote for that machine first (`chi remote add <name> <url>`,
+through an `ssh -L` tunnel if that is how you reach it — docs/cli.md "Through
+an SSH tunnel"). Then, with the host and the chi session's first 8 chars:
+
+```sh
+ssh <host> rm -f /tmp/claude-peer-<id8>.sock
+ssh -N -o ExitOnForwardFailure=yes -R /tmp/claude-peer-<id8>.sock:"$CLAUDE_CODE_MESSAGING_SOCKET" <host>
+```
+
+Run the second in the background: it must keep running while chi may send. If
+ssh wants a password or 2FA, print both lines with the socket spelled out and
+ask the user to run them in a terminal. The `rm -f` matters: a stale remote
+socket is not replaced unless the **server's** sshd has `StreamLocalBindUnlink
+yes` (the client's `-o StreamLocalBindUnlink` covers `-L` only). A server with
+`AllowStreamLocalForwarding no` refuses the forward at start
+(`ExitOnForwardFailure`): tell the user, there is no fallback.
+
+Then pair through the remote:
+
+```sh
+CHI_REMOTE=<name> sh "__CHI_PEER_PAIR__" --inbox-socket /tmp/claude-peer-<id8>.sock <id>
+```
+
+The socket must be visible to chi's process on that machine (chi runs as the
+SSH user, in the same `/tmp`, not inside a separate container): if `/claude`
+in chi shows the socket **missing** while ssh is running, that is why.
+
+Replies are the same push, through the remote:
+`CHI_REMOTE=<name> chi context push claude-outbox <id>`.
+
+A path in a chi message — a `payload: <path>` file, a file or a diff to check —
+is on `<host>`, not here: read it with `ssh <host> cat <path>` (or the repo
+there). The `Read(...)` permission note for payload files does not apply.
+
+After this Claude session restarts its socket changes: stop the old ssh, run
+both lines again, pair again.
+
+Security: whoever can write to that socket on the remote machine can send
+prompts into this session (sshd makes it the user's, mode 0600 by default).
+Fine on the user's own machine or pod, not on a shared host.
+
 ## Don't loop
 
 Never reply to an acknowledgement, a thanks, or a message that only confirms

data/lib/samagotchi/bundles/claude-peer/scripts/pair

@@ -10,22 +10,45 @@
 # only refreshes the socket: the push carries the new hint. CHI names the chi
 # command (default: chi on the PATH). Through a remote (CHI_REMOTE, or
 # --remote NAME in CHI) chi there can't reach this machine's socket: it
-# attaches claude-outbox only, and says so.
+# attaches claude-outbox only, and says so. With --inbox-socket PATH the hint
+# is PATH instead, a socket on chi's machine made by forwarding this Claude's
+# socket there with `ssh -R`, so chi can send here too (docs/plugins.md).
 set -eu
 
 usage() {
-  echo "usage: pair <chi session id or URL (http://127.0.0.1:4567/#/s/<id>)>" >&2
+  echo "usage: pair [--inbox-socket PATH] <chi session id or URL (http://127.0.0.1:4567/#/s/<id>)>" >&2
   exit 2
 }
 
-[ $# -eq 1 ] || usage
-case "$1" in
-  -h | --help) usage ;;
-  http://* | https://*)
-    id=$(printf '%s\n' "$1" | sed -n 's|.*/s/\([0-9A-Za-z-][0-9A-Za-z-]*\).*|\1|p')
-    [ -n "$id" ] || { echo "pair: no session id in $1 (a chi web URL ends in #/s/<id>)" >&2; exit 2; }
-    ;;
-  *) id=$1 ;;
+# The id (or URL) and, optionally, the socket on chi's machine to send through.
+inbox= target=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --inbox-socket)
+      [ $# -ge 2 ] || usage
+      inbox=$2 shift 2
+      [ -n "$inbox" ] || usage
+      ;;
+    --inbox-socket=*)
+      inbox=${1#--inbox-socket=} shift
+      [ -n "$inbox" ] || usage
+      ;;
+    -h | --help) usage ;;
+    *)
+      [ -z "$target" ] || usage
+      target=$1 shift
+      ;;
+  esac
+done
+[ -n "$target" ] || usage
+
+# A relative path would be chi's cwd, not the forward's remote end: the
+# plugin's check refuses it, so refuse it here with the reason.
+case "$inbox" in
+  "") ;;
+  /*) ;;
+  *) echo "pair: --inbox-socket needs an absolute socket path on chi's machine (the ssh -R forward's remote end): $inbox" >&2
+     exit 2 ;;
 esac
 
 sock=${CLAUDE_CODE_MESSAGING_SOCKET:-}
@@ -33,6 +56,7 @@ if [ -z "$sock" ]; then
   echo "pair: CLAUDE_CODE_MESSAGING_SOCKET isn't set: run this from a Claude Code session (2.1.224 or later)" >&2
   exit 2
 fi
+
 chi=${CHI:-chi}
 
 # The remote, as SessionAccess::Dispatch names it: a --remote NAME (or
@@ -52,6 +76,14 @@ for word in $chi; do
   esac
 done
 
+case "$target" in
+  http://* | https://*)
+    id=$(printf '%s\n' "$target" | sed -n 's|.*/s/\([0-9A-Za-z-][0-9A-Za-z-]*\).*|\1|p')
+    [ -n "$id" ] || { echo "pair: no session id in $target (a chi web URL ends in #/s/<id>)" >&2; exit 2; }
+    ;;
+  *) id=$target ;;
+esac
+
 # A JSON string: backslashes, quotes, tabs and newlines escaped.
 json() {
   printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' |
@@ -70,26 +102,51 @@ attach() {
   fi
 }
 
-if [ -n "$via" ]; then
+# Without a socket chi can reach, only the outbox leg works.
+if [ -n "$via" ] && [ -z "$inbox" ]; then
   attach claude-outbox --why "Claude's answers to what you sent it (claude-peer); Claude runs on another machine: claude_send can't reach it" \
     --hint "latest Claude reply"
   ask=$chi
   [ "$via" = chi ] || ask="CHI_REMOTE=$remote $chi"
   printf '%s\n' "pair: chi is on $remote, so chi can't send to this Claude session (claude_send needs its socket on chi's machine): paired with chi $id, claude-outbox only. Answer chi with $ask context push claude-outbox $id; chi's replies reach you only when the user relays them (or asks you to run $ask send --wait $id)"
+  printf '%s\n' "pair: to let chi send here too, forward this Claude's socket to $remote with ssh -R and pair again with --inbox-socket (the chi-peer skill's \"chi on another machine over SSH\")"
   $chi context ls "$id"
   exit 0
 fi
 
-attach claude-inbox --why "the Claude Code session paired with you: send it parts with claude_send" --hint "$sock"
-text="Claude Code peer inbox
+hint=${inbox:-$sock}
+if [ -z "$inbox" ]; then
+  text="Claude Code peer inbox
 socket: $sock
 claude cwd: $PWD
 paired: $(date '+%Y-%m-%d %H:%M')
 Send to it with the claude_send tool (your skill_claude_peer memory); its answers come as the claude-outbox context."
-printf '{"text":%s,"hint":%s,"summary":%s}\n' "$(json "$text")" "$(json "$sock")" \
-  "$(json "Claude Code paired from $PWD")" | $chi context push claude-inbox "$id" >/dev/null
+  summary="Claude Code paired from $PWD"
+else
+  text="Claude Code peer inbox
+socket: $inbox (on this machine: an ssh -R forward of Claude's socket $sock on Claude's machine)
+claude cwd: $PWD
+paired: $(date '+%Y-%m-%d %H:%M')
+Send to it with the claude_send tool (your skill_claude_peer memory); its answers come as the claude-outbox context.
+If claude_send says the Claude session is gone, the ssh tunnel may be down: tell the user to restart it and pair again."
+  summary="Claude Code paired from $PWD over ssh"
+fi
+
+attach claude-inbox --why "the Claude Code session paired with you: send it parts with claude_send" --hint "$hint"
+printf '{"text":%s,"hint":%s,"summary":%s}\n' "$(json "$text")" "$(json "$hint")" "$(json "$summary")" \
+  | $chi context push claude-inbox "$id" >/dev/null
 
+# An outbox attached by an earlier outbox-only pairing carries the why that
+# says claude_send can't reach Claude; context add never updates an existing
+# source, so replace it (Claude's last answer goes with it).
+if $chi context show claude-outbox --json "$id" 2>/dev/null | grep -q "can't reach it"; then
+  $chi context rm claude-outbox "$id" >/dev/null
+fi
 attach claude-outbox --why "Claude's answers to what you sent it (claude-peer)" --hint "latest Claude reply"
 
-echo "paired with chi $id (socket $sock)"
+if [ -z "$inbox" ]; then
+  echo "paired with chi $id (socket $sock)"
+else
+  echo "paired with chi $id (socket $inbox on chi's machine, forwarded from $sock)"
+fi
 $chi context ls "$id"

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.118.0
+version: 0.119.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.118.0"
+  VERSION = "0.119.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.118.0
+  version: 0.119.0
 platform: ruby
 authors:
 - Dmitry Dedov