# bin
The contents of my bin dir. Useful when I crash, burn, corrupt, despoil, savage, or ravage my system. 


## Paused git tracking

.git renamed to .git.paused, so git no longer sees this as a repo.
.git.paused added to .stignore, so Syncthing won't sync it to other hosts.
To resume later: mv ~/bin/.git.paused ~/bin/.git


## Notes

* fresh-start is the big script that install almost everything
* `~/bin` is the primary git repo on `bigfish`; `clown` has a Syncthing copy for execution only.

1. Run install-pkcs11
1. Download DoD certs and run install-os-dodcerts
1. Run setup-nssdb
1. Run install-nssdb-dodcerts


## bashrc
Read the comments in bashrc. 


## On a new machine...
- Generate an ssh kepair with ssh-keygen -b 2048 -t rsa
- Copy pub key to GitHub account
- Clone from home dir, git clone git@github.com:ahoffer/bin.git

After cloning...
- Copy gitconfig_template to ~/.gitconfig
- Open ~/bin/bashrc. Copy the parts that add ~/bin to the path into ~/.bashrc and source .bashrc
- Source ~/.bashrc
- Set up secret env var in ~/.bashrc

## MCP server

`mcpserve` starts the Desktop Commander MCP server via `npx @wonderwhy-er/desktop-commander@latest`
and writes stderr logs to `~/log/mcpserve.log`.

To expose it from another host over SSH, add an SSH alias such as:

    Host clown-mcp
      HostName clown
      User aaron

Then point Codex at it with an MCP entry like:

    [mcp_servers.clown]
    command = "ssh"
    args = ["clown-mcp", "mcpserve"]

This repo only provides the `mcpserve` wrapper; the Desktop Commander package is downloaded by `npx`
when the command runs.

## Claude Code and Codex wrappers

`claude` and `codex` in `~/bin` resolve the real binary outside `~/bin` and exec it.
This keeps the wrapper predictable and avoids self-invocation.

## bigfish-shell

`bigfish-shell` is the resilient interactive entrypoint from clown to bigfish.
It keeps your local terminal unchanged and uses remote tmux on bigfish so work
survives short SSH disconnects.

Behavior:

1. It connects with `ssh bigfish` and runs `tmux new-session -A -s <name>` on
   bigfish (create-or-attach remote session).
1. If SSH fails, it retries with bounded exponential backoff.
1. It must run in an interactive terminal (TTY). Non-interactive runs fail fast.

Usage:

    bigfish-shell
    bigfish-shell my-session

Optional environment variables:

    BIGFISH_HOST=bigfish
    BIGFISH_TMUX_SESSION=bigfish
    BIGFISH_SSH_MAX_ATTEMPTS=5
    BIGFISH_SSH_MAX_DELAY=8

Why this exists:

* Keeps remote work alive inside tmux on bigfish.
* Avoids any background watchdog process; recovery is explicit and operator driven.

### Claude Code session JSONs

Stored at `~/.claude/projects/`. Each project gets a subdirectory named after its path
slug, for example `-home-aaron-bin`. Each conversation is one UUID-named `.jsonl` file.
Subagent threads nest under a session UUID in a `subagents/` subdirectory.

Global prompt history is at `~/.claude/history.jsonl`.

No rotation is performed. Files accumulate indefinitely.

### Codex session JSONs

Stored at `~/.codex/sessions/2026/MM/DD/` as `rollout-<timestamp>-<uuid>.jsonl`.
Directories are created per calendar day.

Global prompt history is at `~/.codex/history.jsonl`.

Persistent conversation state lives in `~/.codex/state_5.sqlite` with standard SQLite
WAL files alongside it.

No rotation is performed on any of these files.

## Colima scripts

### Fix mixed OCI/Docker v2 image manifest format

Docker 24+ with Colima's containerd-snapshotter enabled stores images in containerd's
OCI format. Base layers pulled from Docker Hub arrive as OCI, while new build layers
get Docker v2 types from the Docker build API. The result is a mixed-manifest image
that skopeo cannot convert to docker-archive format, breaking CI Twistlock scans.

Fix: disable containerd-snapshotter in `~/.colima/default/colima.yaml`:

    docker:
      features:
        containerd-snapshotter: false

Then restart Colima and prune stale snapshotter images before rebuilding:

    colima restart
    docker system prune -a --volumes -f

After the prune, rebuild and repush. The resulting image will have a clean Docker
Schema v2 manifest with all layers as `application/vnd.docker.image.rootfs.diff.tar.gzip`.

Verify with:

    skopeo inspect --raw docker://<registry>/<image>:<tag> \
      | python3 -m json.tool | grep mediaType

Colima launch helpers were removed from `~/bin` to avoid conflicting startup paths.

Removed files:

1. `colima-start-guarded`
1. `start-colima-docker.command`
1. `stop-colima-docker.command`

On clown, Colima-related launchd labels were also disabled:

1. `local.colima.guarded`
1. `homebrew.mxcl.colima`

Check disabled state:

    launchctl print-disabled gui/$(id -u) | rg -i colima

## Xpra on bigfish

See `XPRA_README.md` for full setup, configuration, and troubleshooting.

## Future Enhancements

### Cross-tool lock awareness in cx scripts

`acquire_lock` in `cx.lib` uses a lock name (`build` or `deploy`) to create
`/tmp/<name>-<project-hash>.lock`. Because the names differ, `cxdeploy` can
run concurrently with `qb`, which creates a race: if `cxdeploy` calls
`docker save` while `qb` is mid-`buildx --load` on the same tag, the saved
image can be corrupt or wrong-platform, causing `exec format error` in k8s.

Ideas:

- Add a `check_lock` helper that tests for a conflicting lock name without
  acquiring it. `cxdeploy` could call `check_lock build` and abort (or wait)
  if a build is in progress.
- Alternatively, give `acquire_lock` an optional list of lock names to treat
  as conflicts, so a deploy can refuse to start while any listed lock is held.
- A simpler convention: `cxdeploy` could check for any `/tmp/build-<hash>.lock`
  before proceeding and print a clear warning rather than silently racing.