---
name: shared-folder
description: "EXECUTE file sync now via terminal: run bash ${HERMES_WORKER_DIR}/tools/accessSharedFolder.sh put|get|ls. Never describe transfers or tell the user to do it manually — always run the command yourself on the first turn."
version: 1.1.0
author: Hermes Worker
license: MIT
platforms: [macos]
metadata:
  hermes:
    tags: [shared-folder, scp, kobald, sync, transfer, workspace]
    requires_toolsets: [terminal]
---

# Shared folder sync (kobald volume)

## EXECUTE — do not describe

When the user or task asks to copy, upload, download, sync, or transfer a file to/from kobald, the shared volume, `incoming/`, or `workspace/`:

1. **Run the transfer in the terminal on your first turn.** Use the `terminal` tool with **`timeout: 14400`** (4 hours). Never use 60, 180, or 300 — that causes exit 124 and truncated files.
2. **Never** reply with instructions for the user to run scp/rsync/bash themselves.
3. **Never** say "you will need to manually transfer", "run this command", or "here is how to transfer" without also having already executed it.
4. **Never** stop after `ls` or confirming the file exists — existence checks are prep only; the next action must be `put` or `get`.
5. Success means the terminal printed `verified remote size:` or `verified local size:` — report that output, not your intention to transfer.

If prerequisites are missing (remote parent dir, local parent dir), fix them with `mkdir -p` or `ls`, then **immediately** run `put`/`get` in the same session. Do not end the turn after fixing prerequisites.

```bash
TOOL="${HERMES_WORKER_DIR}/tools/accessSharedFolder.sh"
# terminal tool: timeout MUST be 14400
bash "$TOOL" put "/absolute/local/path" "workspace/incoming/filename"
```

## Terminal timeout (mandatory)

Hermes kills terminal commands that exceed their `timeout` parameter (exit code **124**). Large uploads need **14400 seconds (4 hours)**.

Every `terminal` call that runs `accessSharedFolder.sh` must set **`timeout` to `14400`**. Do not omit timeout (defaults can be 60–180s). Do not use smaller values.

Copy files between this Mac and the remote Hermes PVC host path. **Always** use the wrapper script — never `scp`, `rsync`, `sftp`, or `ssh` file copy to the shared host.

## Script

```bash
TOOL="${HERMES_WORKER_DIR}/tools/accessSharedFolder.sh"
```

Config comes from `hermes-worker.yaml` (`shared_folder_remote_host`, `shared_folder_remote_base`) via env vars `SHARED_FOLDER_REMOTE_HOST` and `SHARED_FOLDER_REMOTE_BASE`.

## Commands

```bash
# List remote volume root or a subdirectory
bash "$TOOL" ls
bash "$TOOL" ls workspace

# Download remote → Mac (local parent dir must already exist)
bash "$TOOL" get workspace/foo.txt /Users/you/Downloads/foo.txt
bash "$TOOL" get workspace/data/out.csv /Volumes/MyDrive/incoming/out.csv

# Upload Mac → remote (remote parent dir must already exist)
bash "$TOOL" put /Users/you/file.txt workspace/incoming/file.txt
bash "$TOOL" put /Volumes/Drive/data.zip workspace/uploads/data.zip
```

## Path rules

| Side | Rule |
|------|------|
| Remote | Relative to volume root only (e.g. `workspace/foo.txt`). No `..`, no absolute paths. |
| Local | Any absolute Mac path (`/Users/...`, `/Volumes/...`). |

## Existence rules (script does not create directories)

| Command | Must exist before running |
|---------|---------------------------|
| `put` | Local source file or directory |
| `put` | Remote **parent** directory of destination |
| `get` | Remote source file or directory |
| `get` | Local **parent** directory of destination |

**Before `put`:** verify remote target folder exists (`bash "$TOOL" ls workspace/incoming`). Create remote dirs on the server out-of-band if needed — the script will not `mkdir` on the remote.

**Before `get`:** create the local destination directory with `mkdir -p` (terminal or file tools), then run `get`.

## Common remote paths

| Remote rel | Typical use |
|------------|-------------|
| `workspace/` | Pod workspace (`/opt/data/workspace` inside container) |
| `workspace/incoming/` | Files uploaded from Mac for the agent pod |
| `workspace/outgoing/` | Files to download to Mac |

## Hard rules

1. **Execute** every transfer yourself via `terminal` — no manual handoff to the user.
2. **Never** use raw `scp`, `rsync`, `sftp`, or `ssh … cat/cp` to transfer files to/from the shared volume.
3. **Always** use `accessSharedFolder.sh` for any cross-machine file sync.
4. On failure, read the script error — missing parent dirs are the most common cause.
5. The script **verifies byte size** after each transfer (polls and retries scp on mismatch). Wait for `verified remote/local size: N bytes` before treating the transfer as complete.
6. Large files can take many minutes — use **terminal timeout 14400** (4h). Do not report success until the script prints `verified remote size` or exits 0.

## Worker vs direct shell

When Hermes runs this script via the terminal tool, a short `timeout` on the tool call (e.g. 60s) kills scp mid-transfer (exit 124) before verification runs. The hermes-worker sets `TERMINAL_TIMEOUT=14400` as the default, but you must still pass **`timeout: 14400`** on the terminal tool call. If a transfer is interrupted, the script removes the incomplete remote file on exit.