Resident Workers vs. Client-Owned Workers in Prime Agent: Architecture and Lifecycle Differences

Resident workers are persistent daemon-managed processes that own session state, kernels, and queues to survive client disconnects, while client-owned workers are ephemeral headless processes strictly bound to the client lifecycle and hidden from global listings.

Prime Agent, the open-source coding agent framework from PrimeIntellect-ai, utilizes two distinct worker paradigms to handle interactive and automated workloads. Understanding the difference between resident workers and client-owned workers in Prime Agent is essential for deciding whether a session should persist for re-attachment or execute as a disposable, headless task. These worker types are defined in the daemon supervisor and CLI logic, determining how state is archived, how resources are scheduled, and whether a process remains visible after the client detaches.

What Are Resident Workers?

Resident workers form the backbone of Prime Agent's durable session management. When you launch a standard interactive session, the daemon supervisor spawns a resident worker that maintains ownership of the entire execution context.

Session Ownership and Persistent State

According to the architecture documented in packages/coding-agent/docs/daemon.md, a resident worker owns the root session, its IPython kernel, scheduled jobs, persisted artifacts, and the event queue. This ownership persists even when the client disconnects, allowing users to re-attach later without losing computational context. The supervisor tracks these workers in packages/coding-agent/src/modes/daemon/daemon-supervisor.ts, maintaining descriptors that enable recovery and lifecycle management commands such as restart and snapshot.

Visibility and Global Integration

Resident workers participate fully in the Prime Agent ecosystem. They appear in global listings (e.g., daemon list), engage in peer routing, and respect default schedules. Because they own persistent queues as detailed in packages/coding-agent/docs/long-running-agents.md, they continue processing scheduled tasks regardless of client connectivity.

What Are Client-Owned Workers?

Client-owned workers provide a lightweight alternative for non-interactive, disposable computation. These workers are created when the client explicitly requests a headless session, typically via the --no-session flag.

Ephemeral Lifecycle and Headless Execution

As implemented in packages/coding-agent/src/cli/owned-session-worker.ts, client-owned workers are bound strictly to the client that launched them. They do not own persistent queues or session state; instead, they hold only transient resources necessary for the immediate request. When the client disconnects or the task completes, the supervisor tears down the worker without archiving state, making them ideal for CI pipelines and one-off scripts.

Isolation from Global State

Unlike resident workers, client-owned workers are hidden from global listings and omitted from default schedules and peer routing. The supervisor treats them as disposable headless processes, meaning they cannot be renamed, recovered, or re-attached by other clients. This isolation ensures that ephemeral tasks do not pollute the global worker registry.

Key Architectural Differences

Comparing these worker types reveals four fundamental distinctions:

• Lifecycle Management — Resident workers are managed by the daemon supervisor independently of client connectivity and survive crashes and disconnects. Client-owned workers have lifecycles strictly coupled to the client process and terminate immediately upon client exit.

• State Ownership — Resident workers own the session queue, kernel, schedules, and artifacts in packages/coding-agent/src/modes/daemon/daemon-supervisor.ts. Client-owned workers hold no persistent state; all context disappears after execution.

• Visibility — Resident workers are visible in daemon list and participate in global routing. Client-owned workers are hidden from global listings unless explicitly addressed by the owning client.

• Typical Use Cases — Resident workers support interactive REPL sessions, long-running notebooks, and debugging workflows requiring re-attachment. Client-owned workers handle batch scripts, automated CI jobs, and ephemeral data processing tasks.

Implementation in Source Code

The distinction manifests clearly in the supervisor's registration logic.

Daemon Supervisor Logic

In packages/coding-agent/src/modes/daemon/daemon-supervisor.ts, the supervisor checks the worker profile to determine persistence:

// Resident worker registration
if (profile.isResident) {
  this.registerResidentWorker(workerDescriptor);
  // Worker persists session queue, kernel, and schedules
}

// Client-owned worker cleanup
if (profile.isClientOwned) {
  // Headless worker removed without archiving
  this.cleanupClientOwnedWorker(workerDescriptor);
}

CLI Invocation Flags

The packages/coding-agent/src/cli/owned-session-worker.ts file handles the --no-session flag that triggers client-owned mode:

// Launching a client-owned worker
const worker = await supervisor.createWorker({
  clientOwned: true,
  session: null,  // No persistent session attached
});

Practical Usage Examples

Start a durable interactive session using a resident worker:

# Default interactive mode creates a resident worker

prime-agent

Execute a headless script in an ephemeral client-owned worker:

# The --no-session flag creates a client-owned worker

prime-agent --no-session ./data-processing-script.py

Programmatically, the supervisor differentiates them through descriptor flags:

// From daemon-supervisor.ts
const residentDescriptor = {
  id: 'worker-123',
  type: 'resident',
  ownsQueue: true,
  persistentKernel: true
};

const clientOwnedDescriptor = {
  id: 'worker-456',
  type: 'client-owned',
  ownsQueue: false,
  ephemeral: true
};

Summary

• Resident workers are persistent, daemon-managed processes defined in packages/coding-agent/src/modes/daemon/daemon-supervisor.ts that own session state, kernels, and queues, enabling client re-attachment and global visibility.
• Client-owned workers are ephemeral, headless processes implemented in packages/coding-agent/src/cli/owned-session-worker.ts with lifecycles strictly bound to the client, hidden from global listings, and ideal for batch tasks.
• Resident workers maintain state through disconnects as documented in packages/coding-agent/docs/long-running-agents.md, while client-owned workers terminate without archiving.
• Use resident workers for interactive development; use client-owned workers with --no-session for CI/CD and one-off scripts.

Frequently Asked Questions

Can I convert a client-owned worker to a resident worker after creation?

No. The worker type is determined at instantiation via the --no-session flag or API parameter in packages/coding-agent/src/cli/owned-session-worker.ts. Once created as client-owned, the worker lacks the persistent queue and session metadata required for residency. To achieve persistence, you must start a new resident worker and migrate your logic.

Why do resident workers remain visible after I disconnect?

Resident workers own the session queue and kernel state managed by the daemon supervisor in packages/coding-agent/src/modes/daemon/daemon-supervisor.ts. The supervisor intentionally keeps these processes alive to allow re-attachment, snapshots, and continued execution of scheduled tasks documented in packages/coding-agent/docs/daemon.md.

Do client-owned workers support IPython kernels?

Client-owned workers execute in a headless mode without persistent kernels. While they may access kernel functionality transiently, they do not own or persist kernel state between executions. For interactive kernel sessions that survive disconnection, resident workers are required.

How does the daemon supervisor handle crashes in resident workers?

The supervisor tracks resident worker descriptors in packages/coding-agent/src/modes/daemon/daemon-supervisor.ts, enabling automatic restart and state recovery. Client-owned workers lack this tracking; if they crash, they terminate without recovery or archival.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}