CHORUS/docs/comprehensive/commands/chorus.md

# chorus - Deprecated Compatibility Wrapper

**Binary:** `chorus`
**Source:** `cmd/chorus/main.go`
**Status:** ⚠️ **DEPRECATED** (Removal planned in future version)
**Purpose:** Compatibility wrapper redirecting users to new binaries

---

## Deprecation Notice

**⚠️ THIS BINARY IS DEPRECATED AND SHOULD NOT BE USED ⚠️**

The `chorus` binary has been **replaced** by specialized binaries:

| Old Binary | New Binary | Purpose |
|------------|------------|---------|
| `./chorus` | `./chorus-agent` | Autonomous AI agents |
| `./chorus` | `./chorus-hap` | Human Agent Portal |

**Migration Deadline:** This wrapper will be removed in a future version. All deployments should migrate to the new binaries immediately.

---

## Overview

The `chorus` binary is a **compatibility wrapper** that exists solely to inform users about the deprecation and guide them to the correct replacement binary. It does **not** provide any functional capabilities and will exit immediately with an error code.

### Why Deprecated?

**Architectural Evolution:**

The CHORUS system evolved from a single-binary model to a multi-binary architecture to support:

1. **Human Participation**: Enable humans to participate in agent networks as peers
2. **Separation of Concerns**: Different UIs for autonomous vs human agents
3. **Specialized Interfaces**: Terminal and web interfaces for humans
4. **Clearer Purpose**: Binary names reflect their specific roles

**Old Architecture:**
```
chorus (single binary)
└─→ All functionality combined
```

**New Architecture:**
```
chorus-agent (autonomous operation)
├─→ Headless execution
├─→ Automatic task acceptance
└─→ AI-driven decision making

chorus-hap (human interface)
├─→ Terminal interface
├─→ Web interface (planned)
└─→ Interactive prompts
```

---

## Usage (Deprecation Messages Only)

### Help Output

```bash
$ ./chorus --help
⚠️ CHORUS 0.5.0-dev - DEPRECATED BINARY

This binary has been replaced by specialized binaries:

🤖 chorus-agent    - Autonomous AI agent for task coordination
👤 chorus-hap      - Human Agent Portal for human participation

Migration Guide:
  OLD: ./chorus
  NEW: ./chorus-agent     (for autonomous agents)
       ./chorus-hap       (for human agents)

Why this change?
  - Enables human participation in agent networks
  - Better separation of concerns
  - Specialized interfaces for different use cases
  - Shared P2P infrastructure with different UIs

For help with the new binaries:
  ./chorus-agent --help
  ./chorus-hap --help
```

### Version Output

```bash
$ ./chorus --version
CHORUS 0.5.0-dev (DEPRECATED)
```

### Direct Execution (Error)

```bash
$ ./chorus
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!

This binary has been replaced with specialized binaries:
  🤖 chorus-agent - For autonomous AI agents
  👤 chorus-hap   - For human agent participation

Please use one of the new binaries instead:
  ./chorus-agent --help
  ./chorus-hap --help

This wrapper will be removed in a future version.

# Exit code: 1
```

**Important:** The binary exits with code **1** to prevent accidental use in scripts or deployments.

---

## Source Code Analysis

### File: `cmd/chorus/main.go`

**Lines:** 63
**Package:** main
**Imports:**
- `chorus/internal/runtime` - Only for version constants

**Purpose:** Print deprecation messages and exit

### Complete Source Breakdown

#### Lines 1-9: Package Declaration and Imports

```go
package main

import (
    "fmt"
    "os"

    "chorus/internal/runtime"
)
```

**Note:** Minimal imports since binary only prints messages.

#### Lines 10-12: Deprecation Comment

```go
// DEPRECATED: This binary is deprecated in favor of chorus-agent and chorus-hap
// This compatibility wrapper redirects users to the appropriate new binary
```

**Documentation:** Clear deprecation notice in code comments.

#### Lines 13-29: main() Function

```go
func main() {
    // Early CLI handling: print help/version/deprecation notice
    for _, a := range os.Args[1:] {
        switch a {
        case "--help", "-h", "help":
            printDeprecationHelp()
            return
        case "--version", "-v":
            fmt.Printf("%s %s (DEPRECATED)\n", runtime.AppName, runtime.AppVersion)
            return
        }
    }

    // Print deprecation warning for direct execution
    printDeprecationWarning()
    os.Exit(1)
}
```

**Flow:**

1. **CLI Argument Parsing** (lines 15-24):
   - Check for `--help`, `-h`, `help`: Print help and exit 0
   - Check for `--version`, `-v`: Print version with deprecation tag and exit 0
   - No arguments or unknown arguments: Continue to deprecation warning

2. **Deprecation Warning** (lines 26-28):
   - Print warning message to stderr
   - Exit with code 1 (error)

**Exit Codes:**

| Scenario | Exit Code | Purpose |
|----------|-----------|---------|
| `--help` | 0 | Normal help display |
| `--version` | 0 | Normal version display |
| Direct execution | 1 | Prevent accidental use |
| Unknown arguments | 1 | Force user to read deprecation message |

#### Lines 31-52: printDeprecationHelp()

```go
func printDeprecationHelp() {
    fmt.Printf("⚠️ %s %s - DEPRECATED BINARY\n\n", runtime.AppName, runtime.AppVersion)
    fmt.Println("This binary has been replaced by specialized binaries:")
    fmt.Println()
    fmt.Println("🤖 chorus-agent    - Autonomous AI agent for task coordination")
    fmt.Println("👤 chorus-hap      - Human Agent Portal for human participation")
    fmt.Println()
    fmt.Println("Migration Guide:")
    fmt.Println("  OLD: ./chorus")
    fmt.Println("  NEW: ./chorus-agent     (for autonomous agents)")
    fmt.Println("       ./chorus-hap       (for human agents)")
    fmt.Println()
    fmt.Println("Why this change?")
    fmt.Println("  - Enables human participation in agent networks")
    fmt.Println("  - Better separation of concerns")
    fmt.Println("  - Specialized interfaces for different use cases")
    fmt.Println("  - Shared P2P infrastructure with different UIs")
    fmt.Println()
    fmt.Println("For help with the new binaries:")
    fmt.Println("  ./chorus-agent --help")
    fmt.Println("  ./chorus-hap --help")
}
```

**Content Breakdown:**

| Section | Lines | Purpose |
|---------|-------|---------|
| Header | 32-33 | Show deprecation status with warning emoji |
| Replacement Info | 34-36 | List new binaries and their purposes |
| Migration Guide | 37-41 | Show old vs new commands |
| Rationale | 42-46 | Explain why change was made |
| Next Steps | 47-51 | Direct users to help for new binaries |

**Design:** User-friendly guidance with:
- Clear visual indicators (emojis)
- Side-by-side comparison (OLD/NEW)
- Contextual explanations (Why?)
- Actionable next steps (--help commands)

#### Lines 54-63: printDeprecationWarning()

```go
func printDeprecationWarning() {
    fmt.Fprintf(os.Stderr, "⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!\n\n")
    fmt.Fprintf(os.Stderr, "This binary has been replaced with specialized binaries:\n")
    fmt.Fprintf(os.Stderr, "  🤖 chorus-agent - For autonomous AI agents\n")
    fmt.Fprintf(os.Stderr, "  👤 chorus-hap   - For human agent participation\n\n")
    fmt.Fprintf(os.Stderr, "Please use one of the new binaries instead:\n")
    fmt.Fprintf(os.Stderr, "  ./chorus-agent --help\n")
    fmt.Fprintf(os.Stderr, "  ./chorus-hap --help\n\n")
    fmt.Fprintf(os.Stderr, "This wrapper will be removed in a future version.\n")
}
```

**Key Differences from Help:**

| Aspect | printDeprecationHelp() | printDeprecationWarning() |
|--------|------------------------|---------------------------|
| **Output Stream** | stdout | **stderr** |
| **Verbosity** | Detailed explanation | Brief warning |
| **Tone** | Educational | Urgent |
| **Exit Code** | 0 | **1** |
| **Context** | User requested help | Accidental execution |

**Why stderr?**

- Ensures warning appears in logs
- Distinguishes error from normal output
- Prevents piping warning into scripts
- Signals abnormal execution

**Why brief?**

- User likely expected normal execution
- Quick redirection to correct binary
- Reduces noise in automated systems
- Clear that this is an error condition

---

## Migration Guide

### For Deployment Scripts

**Old Script:**
```bash
#!/bin/bash
# DEPRECATED - DO NOT USE

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=chorus-worker-1

# This will fail with exit code 1
./chorus
```

**New Script (Autonomous Agent):**
```bash
#!/bin/bash
# Updated for chorus-agent

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=chorus-worker-1
export CHORUS_P2P_PORT=9000

# Use new agent binary
./chorus-agent
```

**New Script (Human Agent):**
```bash
#!/bin/bash
# Updated for chorus-hap

export CHORUS_LICENSE_ID=prod-123
export CHORUS_AGENT_ID=human-alice
export CHORUS_HAP_MODE=terminal

# Use new HAP binary
./chorus-hap
```

### For Docker Deployments

**Old Dockerfile:**
```dockerfile
FROM debian:bookworm-slim
COPY chorus /usr/local/bin/chorus
ENTRYPOINT ["/usr/local/bin/chorus"]  # DEPRECATED
```

**New Dockerfile (Agent):**
```dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates docker.io
COPY chorus-agent /usr/local/bin/chorus-agent
ENTRYPOINT ["/usr/local/bin/chorus-agent"]
```

**New Dockerfile (HAP):**
```dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY chorus-hap /usr/local/bin/chorus-hap
ENTRYPOINT ["/usr/local/bin/chorus-hap"]
```

### For Docker Compose

**Old docker-compose.yml:**
```yaml
services:
  chorus:  # DEPRECATED
    image: chorus:latest
    command: /chorus  # Will fail
```

**New docker-compose.yml (Agent):**
```yaml
services:
  chorus-agent:
    image: chorus-agent:latest
    command: /usr/local/bin/chorus-agent
    environment:
      - CHORUS_LICENSE_ID=${CHORUS_LICENSE_ID}
```

**New docker-compose.yml (HAP):**
```yaml
services:
  chorus-hap:
    image: chorus-hap:latest
    command: /usr/local/bin/chorus-hap
    stdin_open: true  # Required for terminal interface
    tty: true
    environment:
      - CHORUS_LICENSE_ID=${CHORUS_LICENSE_ID}
      - CHORUS_HAP_MODE=terminal
```

### For Systemd Services

**Old Service File:** `/etc/systemd/system/chorus.service`
```ini
[Unit]
Description=CHORUS Agent (DEPRECATED)

[Service]
ExecStart=/usr/local/bin/chorus  # Will fail
Restart=always

[Install]
WantedBy=multi-user.target
```

**New Service File:** `/etc/systemd/system/chorus-agent.service`
```ini
[Unit]
Description=CHORUS Autonomous Agent
After=network.target docker.service

[Service]
Type=simple
User=chorus
EnvironmentFile=/etc/chorus/agent.env
ExecStart=/usr/local/bin/chorus-agent
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target
```

**Migration Steps:**
```bash
# Stop old service
sudo systemctl stop chorus
sudo systemctl disable chorus

# Install new service
sudo cp chorus-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chorus-agent
sudo systemctl start chorus-agent
```

### For CI/CD Pipelines

**Old Pipeline (GitLab CI):**
```yaml
build:
  script:
    - go build -o chorus ./cmd/chorus  # DEPRECATED
    - ./chorus --version
```

**New Pipeline:**
```yaml
build:
  script:
    - make build-agent  # Builds chorus-agent
    - make build-hap    # Builds chorus-hap
    - ./build/chorus-agent --version
    - ./build/chorus-hap --version
```

### For Kubernetes Deployments

**Old Deployment:**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: chorus  # DEPRECATED
spec:
  template:
    spec:
      containers:
      - name: chorus
        image: chorus:latest
        command: ["/chorus"]  # Will fail
```

**New Deployment:**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: chorus-agent
spec:
  template:
    spec:
      containers:
      - name: chorus-agent
        image: chorus-agent:latest
        command: ["/usr/local/bin/chorus-agent"]
        env:
        - name: CHORUS_LICENSE_ID
          valueFrom:
            secretKeyRef:
              name: chorus-secrets
              key: license-id
```

---

## Build Process

### Current Makefile Targets

The CHORUS Makefile provides migration-friendly targets:

```makefile
# Build all binaries
make all
├─→ make build-agent   # Builds chorus-agent (recommended)
├─→ make build-hap     # Builds chorus-hap (recommended)
└─→ make build-compat  # Builds chorus (deprecated wrapper)
```

### Building Individual Binaries

**Autonomous Agent:**
```bash
make build-agent
# Output: build/chorus-agent
```

**Human Agent Portal:**
```bash
make build-hap
# Output: build/chorus-hap
```

**Deprecated Wrapper:**
```bash
make build-compat
# Output: build/chorus (for compatibility only)
```

### Why Keep the Deprecated Binary?

**Reasons to Build chorus:**

1. **Gradual Migration**: Allows staged rollout of new binaries
2. **Error Detection**: Catches deployments still using old binary
3. **User Guidance**: Provides migration instructions at runtime
4. **CI/CD Compatibility**: Prevents hard breaks in existing pipelines

**Planned Removal:**

The `chorus` binary and `make build-compat` target will be removed in:
- **Version:** 1.0.0
- **Timeline:** After all known deployments migrate
- **Warning Period:** At least 3 minor versions (e.g., 0.5 → 0.6 → 0.7 → 1.0)

---

## Troubleshooting

### Script Fails with "DEPRECATION WARNING"

**Symptom:**
```bash
$ ./deploy.sh
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!
...
# Script exits with error
```

**Cause:** Script uses old `./chorus` binary

**Fix:**
```bash
# Update script to use chorus-agent
sed -i 's|./chorus|./chorus-agent|g' deploy.sh

# Or update to chorus-hap for human agents
sed -i 's|./chorus|./chorus-hap|g' deploy.sh
```

### Docker Container Exits Immediately

**Symptom:**
```bash
$ docker run chorus:latest
⚠️ DEPRECATION WARNING: The 'chorus' binary is deprecated!
# Container exits with code 1
```

**Cause:** Container uses deprecated binary

**Fix:** Rebuild image with correct binary:
```dockerfile
# Old
COPY chorus /usr/local/bin/chorus

# New
COPY chorus-agent /usr/local/bin/chorus-agent
ENTRYPOINT ["/usr/local/bin/chorus-agent"]
```

### Systemd Service Fails to Start

**Symptom:**
```bash
$ sudo systemctl status chorus
● chorus.service - CHORUS Agent
   Active: failed (Result: exit-code)
   Main PID: 12345 (code=exited, status=1/FAILURE)
```

**Cause:** Service configured to run deprecated binary

**Fix:** Create new service file:
```bash
# Disable old service
sudo systemctl stop chorus
sudo systemctl disable chorus

# Create new service
sudo cp chorus-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chorus-agent
sudo systemctl start chorus-agent
```

### CI Build Succeeds but Tests Fail

**Symptom:**
```bash
$ ./chorus --version
CHORUS 0.5.0-dev (DEPRECATED)
# Tests that try to run ./chorus fail
```

**Cause:** Tests invoke deprecated binary

**Fix:** Update test commands:
```bash
# Old test
./chorus --help

# New test
./chorus-agent --help
```

### Can't Find Replacement Binary

**Symptom:**
```bash
$ ./chorus-agent
bash: ./chorus-agent: No such file or directory
```

**Cause:** New binaries not built or installed

**Fix:**
```bash
# Build new binaries
make build-agent
make build-hap

# Binaries created in build/ directory
ls -la build/chorus-*

# Install to system
sudo cp build/chorus-agent /usr/local/bin/
sudo cp build/chorus-hap /usr/local/bin/
```

---

## Migration Checklist

### Pre-Migration Assessment

- [ ] **Inventory Deployments**: List all places `chorus` binary is used
  - Production servers
  - Docker images
  - Kubernetes deployments
  - CI/CD pipelines
  - Developer machines
  - Documentation

- [ ] **Identify Binary Types**: Determine which replacement is needed
  - Autonomous operation → `chorus-agent`
  - Human interaction → `chorus-hap`
  - Mixed use → Both binaries needed

- [ ] **Review Configuration**: Check environment variables
  - `CHORUS_AGENT_ID` naming conventions
  - HAP-specific variables (`CHORUS_HAP_MODE`)
  - Port assignments (avoid conflicts)

### Migration Execution

- [ ] **Build New Binaries**
  ```bash
  make build-agent
  make build-hap
  ```

- [ ] **Update Docker Images**
  - Modify Dockerfile to use new binaries
  - Rebuild and tag images
  - Push to registry

- [ ] **Update Deployment Configs**
  - docker-compose.yml
  - kubernetes manifests
  - systemd service files
  - deployment scripts

- [ ] **Test in Staging**
  - Deploy new binaries to staging environment
  - Verify P2P connectivity
  - Test agent/HAP functionality
  - Validate health checks

- [ ] **Update CI/CD Pipelines**
  - Build configurations
  - Test scripts
  - Deployment scripts
  - Rollback procedures

- [ ] **Deploy to Production**
  - Rolling deployment (one node at a time)
  - Monitor logs for deprecation warnings
  - Verify peer discovery still works
  - Check metrics and health endpoints

- [ ] **Update Documentation**
  - README files
  - Deployment guides
  - Runbooks
  - Architecture diagrams

### Post-Migration Verification

- [ ] **Verify No Deprecation Warnings**
  ```bash
  # Check logs for deprecation messages
  journalctl -u chorus-agent | grep DEPRECATION
  # Should return no results
  ```

- [ ] **Confirm Binary Versions**
  ```bash
  ./chorus-agent --version
  ./chorus-hap --version
  # Should show correct version without (DEPRECATED)
  ```

- [ ] **Test Functionality**
  - [ ] P2P peer discovery works
  - [ ] Tasks execute successfully (agents)
  - [ ] Terminal interface works (HAP)
  - [ ] Health checks pass
  - [ ] Metrics collected

- [ ] **Remove Old Binary**
  ```bash
  # After confirming everything works
  rm /usr/local/bin/chorus
  ```

- [ ] **Clean Up Old Configs**
  - Remove old systemd service files
  - Delete old Docker images
  - Archive old deployment scripts

---

## Comparison with New Binaries

### Feature Comparison

| Feature | chorus (deprecated) | chorus-agent | chorus-hap |
|---------|---------------------|--------------|------------|
| **Functional** | ❌ No | ✅ Yes | ✅ Yes |
| **P2P Networking** | ❌ N/A | ✅ Yes | ✅ Yes |
| **Task Execution** | ❌ N/A | ✅ Automatic | ✅ Interactive |
| **UI Mode** | ❌ N/A | Headless | Terminal/Web |
| **Purpose** | Deprecation notice | Autonomous agent | Human interface |
| **Exit Code** | 1 (error) | 0 (normal) | 0 (normal) |
| **Runtime** | Immediate exit | Long-running | Long-running |

### Size Comparison

| Binary | Size | Notes |
|--------|------|-------|
| `chorus` | ~2 MB | Minimal (messages only) |
| `chorus-agent` | ~25 MB | Full functionality + dependencies |
| `chorus-hap` | ~28 MB | Full functionality + UI components |

**Why is chorus smaller?**
- No P2P libraries linked
- No task execution engine
- No AI provider integrations
- Only runtime constants imported

### Command Comparison

**chorus (deprecated):**
```bash
./chorus --help     # Prints deprecation help
./chorus --version  # Prints version with (DEPRECATED)
./chorus            # Prints warning, exits 1
```

**chorus-agent:**
```bash
./chorus-agent --help     # Prints agent help
./chorus-agent --version  # Prints version
./chorus-agent            # Runs autonomous agent
```

**chorus-hap:**
```bash
./chorus-hap --help     # Prints HAP help
./chorus-hap --version  # Prints version
./chorus-hap            # Runs human interface
```

---

## Related Documentation

- [chorus-agent](chorus-agent.md) - Autonomous agent binary (REPLACEMENT)
- [chorus-hap](chorus-hap.md) - Human Agent Portal binary (REPLACEMENT)
- [internal/runtime](../internal/runtime.md) - Shared runtime initialization
- [Migration Guide](../deployment/migration-v0.5.md) - Detailed migration instructions
- [Deployment](../deployment/docker.md) - Docker deployment guide

---

## Implementation Status

| Feature | Status | Notes |
|---------|--------|-------|
| Deprecation Messages | ✅ Implemented | Help and warning outputs |
| Exit Code 1 | ✅ Implemented | Prevents accidental use |
| Version Tagging | ✅ Implemented | Shows (DEPRECATED) |
| Guidance to New Binaries | ✅ Implemented | Clear migration instructions |
| **Removal Planned** | ⏳ Scheduled | Version 1.0.0 |

### Removal Timeline

| Version | Action | Date |
|---------|--------|------|
| 0.5.0 | Deprecated, wrapper implemented | 2025-09-30 |
| 0.6.0 | Warning messages in logs | TBD |
| 0.7.0 | Final warning before removal | TBD |
| 1.0.0 | **Binary removed entirely** | TBD |

**Recommendation:** Migrate immediately. Do not wait for removal.

---

## FAQ

### Q: Can I still use `./chorus`?

**A:** Technically you can build it, but it does nothing except print deprecation warnings and exit with error code 1. You should migrate to `chorus-agent` or `chorus-hap` immediately.

### Q: Will `chorus` ever be restored?

**A:** No. The architecture has permanently moved to specialized binaries. The `chorus` wrapper exists only to guide users to the correct replacement.

### Q: What if I need both agent and HAP functionality?

**A:** Run both binaries separately:
```bash
# Terminal 1: Run autonomous agent
./chorus-agent &

# Terminal 2: Run human interface
./chorus-hap
```

Both can join the same P2P network and collaborate.

### Q: How do I test if my deployment uses the deprecated binary?

**A:** Check for deprecation warnings in logs:
```bash
# Grep for deprecation messages
journalctl -u chorus | grep "DEPRECATION WARNING"
docker logs <container> 2>&1 | grep "DEPRECATION WARNING"

# If found, migration is needed
```

### Q: Is there a compatibility mode?

**A:** No. The `chorus` binary is intentionally non-functional to force migration. There is no compatibility mode.

### Q: What about shell scripts that call `./chorus`?

**A:** Update them to call `./chorus-agent` or `./chorus-hap`. Use `sed` for bulk updates:
```bash
# Update all scripts in directory
find . -type f -name "*.sh" -exec sed -i 's|./chorus[^-]|./chorus-agent|g' {} +
```

### Q: Will old Docker images still work?

**A:** No. Docker images built with the `chorus` binary will fail at runtime with deprecation warnings. Rebuild images with new binaries.

### Q: Can I delay migration?

**A:** You can delay, but the wrapper will be removed in version 1.0.0. Migrate now to avoid emergency updates later.

### Q: Where can I get help with migration?

**A:** See:
- [Migration Guide](../deployment/migration-v0.5.md) - Detailed migration steps
- [chorus-agent Documentation](chorus-agent.md) - Agent replacement details
- [chorus-hap Documentation](chorus-hap.md) - HAP replacement details

---

**Last Updated:** 2025-09-30

**Deprecation Status:** Active deprecation since version 0.5.0

**Removal Target:** Version 1.0.0