Port Daddy

Port Daddy v3.8.2 — Agent Coordination That Actually Works

NOT for

• Production deployment orchestration, rollout policy, or CI release gating.
• Docker, Kubernetes, service-mesh, or cloud network discovery problems.
• Single-agent local work where no port coordination, salvage, or shared-state workflow exists.

The Problem You Have Right Now

You're an AI agent. You're about to start a dev server. Which port? 3000? Taken. 3001? Another agent grabbed it. You pick a random port. Now nothing can find your server.

Meanwhile, another agent is editing the same file you are. Neither of you knows. You'll both commit. One of you loses work.

A third agent crashed 20 minutes ago — halfway through a migration. Its work is orphaned. Nobody knows.

Port Daddy solves all of this in one daemon.

Decision Tree — Pick the Right Primitive

Read top-to-bottom. The first matching leaf is your answer. If you skip the daemon-up check, every subsequent decision is meaningless.

flowchart TD
  A[I want to do something coordination-shaped] --> Up{pd status<br/>== running?}
  Up -- no --> Down[examples/06-debug-daemon-down.md]
  Up -- yes --> Scope{Scope?}

  Scope -- single agent, no shared state --> Out[Out of scope: just code.<br/>NOT for this skill.]
  Scope -- this agent, this session --> Life[Lifecycle path]
  Scope -- two+ agents, same repo --> Coord[Coordination path]
  Scope -- background cadence / fleet --> Fleet[Fleet path]
  Scope -- many agents, same harbor --> Swarm[Swarm path]

  Life --> L1{What do I need?}
  L1 -- "session boundary" --> L1a[pd begin / pd done<br/>schemas/note-shape.md]
  L1 -- "deterministic port" --> L1b[pd claim {project}:{stack}:{ctx}<br/>schemas/semantic-identity.md<br/>examples/07-port-collision.md]
  L1 -- "audit trail" --> L1c[pd note --type ...<br/>assets/session-note.template.md]
  L1 -- "what happened?" --> L1d[pd sitrep / catch_me_up MCP]

  Coord --> C1{Failure mode I'm preventing?}
  C1 -- "two agents edit same file" --> C1a[pd session files claim<br/>examples/02-two-agents-same-file.md]
  C1 -- "must be exclusive" --> C1b[pd with-lock<br/>or pd lock + pd unlock]
  C1 -- "agent-to-agent signal" --> C1c[pd pub + pd watch]
  C1 -- "DM a specific agent" --> C1d[pd inbox send<br/>or talk_to_agent MCP]
  C1 -- "agent died, finish their work" --> C1e[pd salvage claim<br/>schemas/salvage-entry.md<br/>examples/03-salvage]

  Fleet --> F1{Fleet exists?}
  F1 -- "no" --> F1a[pd fleet init + edit pd-fleet.yml<br/>assets/pd-fleet.starter.yml<br/>examples/04-fleet-from-zero.md]
  F1 -- "yes, broken" --> F1b[scripts/fleet-validate.sh<br/>schemas/pd-fleet.schema.md]
  F1 -- "yes, want it daemon-managed" --> F1c[POST /fleet/register<br/>survives terminal close]
  F1 -- "yes, want to chain agents" --> F1d[on_success: publish channel<br/>+ declare in channels:]

  Swarm --> S1{Shape of the data?}
  S1 -- "typed records, multi-reader" --> S1a[pd tuple out + pd tuple rd<br/>schemas/tuple-shape.md]
  S1 -- "exactly-once work" --> S1b[pd tuple in<br/>work-stealing<br/>examples/05-tuple-swarm-handoff.md]
  S1 -- "ambient gradient / heat" --> S1c[pd pheromone spray<br/>schemas/pheromone-signal.md]
  S1 -- "broadcast, ephemeral" --> S1d[pd pub on a harbor channel]

The five questions, in order:

1. Daemon up? — pd status. If not, you have no coordination at all. Fix this first.
2. Scope? — single-session, two-agent, fleet (cadence), or swarm (many-in-harbor)? They use different primitives; mixing them is theatre.
3. What failure mode am I preventing? — silent overwrite, port conflict, dead-agent loss, missed signal? The failure mode chooses the primitive.
4. Durable or ephemeral? — notes (forever) and tuples-with-no-TTL (until-removed) are durable. Pheromones and pub/sub are ephemeral. Picking the wrong one either pollutes the audit trail or loses signal.
5. Read-many or take-once? — tuple rd and pub are fan-out; tuple in and lock are exactly-one-winner. Get this wrong and you either drop work or duplicate it.

Failure-Mode Triage

When something is already broken, jump straight here.

L3 Index — Where the Deep Knowledge Lives

This file is the L1/L2 entry. Don't paste deep references inline — load on demand:

Quick Start (Do This First)

# 1. Start your session — ALWAYS do this first
pd begin "Building auth module"

# 2. Claim a port — deterministic, never conflicts
PORT=$(pd claim myapp:api:main -q)

# 3. Leave breadcrumbs for other agents
pd note "JWT validation working, moving to refresh tokens"

# 4. Check who else is working here
pd salvage --project myapp    # Any dead agents to rescue?

# 5. End cleanly
pd done

Why This Matters

Without Port Daddy:

• Port conflicts every time two agents run dev servers
• No record of what agents did or decided
• Crashed agents leave orphaned work nobody finds
• No way for agents to signal each other
• File edit collisions destroy work silently

With Port Daddy:

• Deterministic ports — same identity always gets the same port
• Immutable notes — full audit trail of every decision
• Salvage queue — dead agent work is preserved and claimable
• Pub/sub + file claims — agents coordinate without stepping on each other
• Background fleet — QA, docs, testing run automatically on every commit
• Binary IPC — sub-microsecond heartbeats and pheromone sprays over Unix socket
• Pheromone trails — ambient numeric signals that decay over time for contention detection
• Tuple space — shared typed memory for swarm coordination
• Semantic trie — O(k) identity lookups replacing SQL LIKE scans

Shibboleths

• If the task only needs one temporary port and no shared session state, launching fleets and pheromone trails is theater, not coordination.
• If you need hard exclusion for a critical section, use a lock; advisory file claims are for negotiation, not safety.
• If the failure is in container ingress, DNS, or production service discovery, Port Daddy is the wrong layer.

MCP Tools Available

Start here (high-level, one call does many things):

Tuple space tools (shared swarm memory):

Discover more tools by category: Call pd_discover with a category name: magic, session-lifecycle, ports, sessions, notes, locks, messaging, agents, inbox, webhooks, integration, dns, briefing, tunnels, projects, changelog, activity, system, tuples, pheromone

Integration signals: Use integration ready and integration needs to coordinate service dependencies. When your service is ready, signal it so other agents can proceed.

Core Concepts

Semantic Identities: project:stack:context

Every service gets a semantic name. The name IS the port — deterministic hashing means the same identity always maps to the same port. Identities are indexed in an in-memory Adaptive Radix Tree for O(k) lookups (where k is key length), replacing SQL LIKE scans.

pd claim myapp:api:main           # Always gets port 3142 (or whatever hash gives)
pd claim myapp:api:feature-auth   # Different port, same project
pd find 'myapp:*'                 # Prefix search — resolves through the trie, not SQL
pd find 'myapp:*:main'            # Wildcard — all stacks with context "main"

Sessions & Notes

Sessions track what each agent is doing. Notes are immutable — once written, they can never be edited or deleted. This creates an audit trail that agents and humans can trust. Notes are encrypted at rest with AES-256-GCM (master key at ~/.port-daddy/master.key, auto-generated on first boot).

pd begin --identity myapp:api --purpose "Building auth"
pd note "Found SQL injection in token validation"
pd note "Patched. Tests green."
pd done

Salvage (Dead Agent Recovery)

When an agent crashes, its session enters the salvage queue. Another agent can claim and continue the work:

pd salvage --project myapp        # See dead agents' context
pd salvage claim dead-agent-42    # Pick up their work

IMPORTANT: Always check pd salvage at the start of a session. You might be able to continue where a crashed agent left off instead of starting from scratch.

File Claims (Advisory)

pd session files claim src/auth/*.ts
# Another agent tries the same file:
pd session files claim src/auth/login.ts
# → CONFLICT: claimed by agent 'myapp:api'

Claims are advisory — they warn, don't lock. Hard locks cause deadlocks. Advisory claims cause conversations.

Pub/Sub Messaging

Agents signal each other through channels:

# Agent A finishes database setup
pd pub myapp:events "database-ready"

# Agent B was watching
pd watch myapp:events --exec "npm run migrate"

Distributed Locks

For operations that truly must be exclusive:

pd with-lock deployment -- npm run deploy
# Or manually:
pd lock db-migration --ttl 300
pd unlock db-migration

Binary IPC Protocol (v3.8.2)

High-frequency agent communication over a Unix domain socket with MessagePack encoding. The IPC channel sits alongside the HTTP API — agents that need low-latency communication (heartbeats, pheromone sprays, pub/sub publish) use IPC automatically when the daemon is running.

Key properties:

• 7-byte header: [type:1][conv_id:4][payload_len:2] + MessagePack payload
• 70-80% bandwidth reduction vs HTTP JSON
• ~3us latency for fire-and-forget operations (vs ~200us HTTP)
• 13 FIPA performatives: INFORM, REQUEST, QUERY_REF, REFUSE, FAILURE, NOT_UNDERSTOOD, SUBSCRIBE, UNSUBSCRIBE, etc.
• Fire-and-forget: heartbeats, pheromone sprays, pub/sub publish (conv_id=0)
• Request-response: claims, locks, sessions (conv_id for correlation)
• Pub/sub subscriptions: with dead-man cleanup on disconnect
• Auto-reconnect: client reconnects with subscription replay on socket drop
• SDK fast paths: heartbeat(), pheromoneSpray(), publish() auto-use IPC when available

Socket location: ~/.port-daddy/daemon.ipc

Security hardening:

• Rate limiting: 500 frames/sec per connection
• Connection limit: 256 max (REFUSE for excess)
• 3-strike protocol violation budget (malformed frames disconnect)
• Backpressure via write queue + drain events
• Lock release on IPC disconnect

You don't need to use IPC directly. The SDK and CLI use it transparently for hot-path operations.