Agent Orchestration Architecture & Security

This guide is for company administrators, security teams, network teams, and platform teams that need to review, approve, and operate IntuitivePM agent orchestration.

Agent orchestration keeps IntuitivePM as the control plane. External runtimes connect outward to IntuitivePM, claim assigned work, report progress, and return completion evidence. The customer decides which agent identities, runtimes, workspaces, models, and tools are allowed.

Component Responsibilities

The runtime bridge is intentionally narrow. It is not a generic remote shell, not a public callback endpoint, and not a general API proxy.

Customer deployments should use the smallest approved runtime artifact that fits the host model: a versioned runtime package for Ubuntu/systemd hosts or an approved container image for Docker and Kubernetes. Avoid using a full application source checkout as the normal runtime delivery mechanism.

Required Network Access

Most external-runtime deployments require outbound access only.

Firewall And Proxy Checklist

Allow:

• DNS resolution for api.intuitivepm.net.
• Outbound TCP 443 to api.intuitivepm.net.
• HTTPS requests with standard JSON request and response bodies.
• WebSocket upgrade over TLS for /agent-ws.
• Long-lived WebSocket connections, or a proxy timeout long enough for your runtime policy.
• Outbound access to approved Git, documentation, model, or internal endpoints only when the runtime needs them.

Avoid:

• Blocking WebSocket upgrade headers.
• Rewriting request bodies sent to the Agent API.
• Injecting secrets into logs at the proxy layer.
• Allowing broad outbound internet access when the runtime only needs IntuitivePM and a small set of approved systems.

If TLS inspection is used, validate it with a smoke runtime before enabling production execution. The runtime must still verify a trusted TLS chain.

Authentication And Authorization

External runtimes do not use human browser sessions.

1. A company administrator creates or approves an external agent identity in Agent Registry.
2. The administrator creates credentials for that agent identity.
3. The runtime exchanges its client ID, client secret, and runtime ID for a short-lived agent token.
4. The runtime uses the short-lived token for Agent API calls and WebSocket connection.
5. IntuitivePM enforces company scope, agent scope, runtime approval, work assignment, and lease ownership.

The client secret should be stored in a secret manager, protected environment file, Kubernetes Secret, Docker secret, or equivalent platform secret store. Rotate the credential if it is exposed.

Scopes And Least Privilege

Assign only the scopes needed for the runtime.

Execution agents normally need narrower scopes than orchestrators. Do not give an execution-only runtime review/control permissions unless it is explicitly approved for that responsibility.

AI-Assisted Configuration Data Flow

Agent Registry AI Assist is an administrator action inside IntuitivePM. It sends the selected agent’s registry metadata, runtime metadata, current capability profile, and proposed profile draft to company-approved AI services. The flow uses a primary model for the draft, a reviewer model when another approved model is available, and the primary model again to resolve feedback.

The draft is returned to the administrator with confidence markers and review details. It is not saved automatically, and it does not grant runtime access, credentials, repository access, or Work Files permissions. Normal company AI provider settings, model approvals, billing, and audit controls still apply.

Runtime-reported capability claims follow the same trust boundary. A runtime can submit a proposed capability profile draft, runtime tag suggestions, and evidence through the Agent API, but IntuitivePM stores it as pending review. Dispatch does not consume raw claims. Company admins must approve or reject the claim in Agent Registry and explicitly choose whether it updates the reviewed capability profile or runtime tags. The review UI compares pending claims with the current reviewed profile and runtime tags so security reviewers can see exactly what would change.

Data Sent To External Runtimes

The runtime can receive data needed to perform assigned work. Depending on the task, this may include:

• Task and subtask title, description, status, priority, assignee, project, labels, and due dates.
• Agent instructions, orchestrator/reviewer instructions, and completion evidence expectations.
• Relevant task comments and history needed for context.
• Work Files attached to the task or accessible under the owning member’s permissions.
• Git links, documentation requirements, and approved repository or documentation context.
• Stop, reload, waiting, progress, and lease-control state.

Do not put secrets into task descriptions, comments, progress messages, or Work Files unless your company has explicitly approved that data path.

Data Written Back To IntuitivePM

Runtimes should write durable outcomes back through IntuitivePM:

• Task comments for questions, caveats, and completion evidence.
• Structured progress events for live visibility.
• Lease heartbeat and completion/failure state.
• Review submission when the assigned work is complete.
• File outputs through Work Files when the task requires generated artifacts.

Progress events are operational visibility. They are not a replacement for comments, completion evidence, task history, or review decisions.

Workspace And File Safety

External execution should run inside an approved workspace root.

Default Work Files permissions are intentionally conservative:

• Read files owned by the member.
• Create new files.
• Update only files last written by the same agent.
• No delete by default.

Full CRUD access requires an explicit member opt-in. Keep approved workspace paths narrow and review runtime manifests before live execution.

Live executor runtimes should also be isolated from other executor sessions on the same host. Use a dedicated Linux user, container, or Kubernetes pod per live runtime so Claude Code, Codex, or similar tools do not share home directories, config/cache/session files, run logs, or writable workspaces with an interactive session or another active runtime.

Review Gate

Agents cannot bypass human or orchestrator review.

The normal flow is:

1. Work enters In Progress.
2. The runtime claims a lease.
3. The executor performs the assigned work.
4. The agent submits completion evidence.
5. The work moves to Review.
6. A human reviewer or orchestrator claims the review decision.
7. A human reviewer or orchestrator accepts to Done or sends it back to In Progress with feedback.

Completion evidence should state whether the work completed with no issues or with caveats. For code or documentation work, include tests run, files changed, and docs touched.

Automated orchestrator review uses an explicit review lease. Execution leases prove who is doing the work; review leases prove who owns the Review decision. This keeps active execution, active review, stale execution, and stale review auditable as separate states.

When agent work enters Review, IntuitivePM sends a review.available wake event to approved online runtimes for the assigned orchestrator. Scoped polling remains the fallback for missed wake events, but the normal path is event-driven. If a human reviewer accepts or returns the work while an automated review lease is active, the active review lease is superseded and the stale automated decision cannot be applied later.

Managed orchestrator runtimes can make the first automated review decision through that review lease. The default reviewer is conservative: it accepts only work that is ready for review, has completion evidence, has a passing quality preview, has no failed criteria, and reports no caveats. If evidence is missing, caveats are present, or the quality preview warns or fails, IntuitivePM returns the work with a concrete review comment instead of accepting it.

Company rule sets control how many automated review returns are allowed before escalation. The default allows two automated returns; after that, failed automated review waits for a human or orchestrator according to company policy instead of looping back to In Progress again.

Escalated waiting states are manual pauses. If a task is waitingOnUser, waitingOnOrchestrator, or needsReload, managed runtimes skip it during review queue polling and IntuitivePM refuses new automated review lease claims for it. A user or orchestrator must resolve the waiting reason before automated review can continue.

During automated review, managed orchestrator runtimes send bounded progress phases such as claiming, checking evidence, checking Git/CI context, accepting, returning, or escalating. These live events drive board badges and dashboards; comments and review history remain the durable audit record.

For operator visibility, IntuitivePM also exposes review lease state through the authenticated user API. The task modal can show active review owner/runtime, review attempt count, active lease expiry, latest retry feedback, escalation reason, and decision summary. Review queue payloads include the latest review lease state so operators and integrations can distinguish unclaimed, claimed, expired, returned, escalated, accepted, and cancelled review ownership. If transient progress expires, executionState=reviewing remains the durable board-card fallback until the review decision completes.

Agent Activity separates execution lease health from review lease health. Administrators can see active review leases, stale review leases, unclaimed review queue, returned review decisions, escalations, and recently expired review leases without mixing them with executor work leases.

IntuitivePM also tests these review controls as part of the orchestration release process. Current automated coverage checks review lease claim guardrails, stale review expiry, human override cancellation, review queue state visibility, orchestrator role and scope denial, targeted review.available delivery to the approved orchestrator runtime, runtime review controller decisions, and deterministic managed-runtime review policy.

Recent immutable outcome history is used as bounded dispatch scoring input. IntuitivePM aggregates completions, failures, expiries/stale leases, cancellations, releases, caveats, review accepts/rejects, and duration per agent/runtime and shows the reliability contribution in dispatch previews. Raw execution logs and transient progress events remain separate from this summary signal. Recent lease rows remain a migration fallback only when no relevant outcome history exists yet.

IntuitivePM records append-only outcome history for dispatch selections, lease claimed/completed/failed/expired/cancelled/released events, and review accepted/rejected decisions. These records are company-scoped and include score details, ranked candidates, caveat signal, timestamps, relevant durations, and review-quality assessments for audit, reporting, and future scoring improvements.

Review-quality assessments are stored with accepted/rejected review outcomes. They score configured review templates and completion evidence, including caveats, evidence presence, tests, documentation, and Git review signals when those templates apply. The Agent Activity dashboard aggregates accepted/rejected reviews, low-quality reviews, and average review-quality score across the projects the viewer can access.

Logging And Audit

IntuitivePM keeps the official task record:

• Task and subtask state.
• Comments.
• Progress events.
• Lease state.
• Review decisions.
• Assignment and orchestration metadata.
• Immutable selection and outcome history.

Managed runtimes may also write local run logs on the runtime host. Local logs are useful for support and audit review, but they should not contain IntuitivePM tokens, provider keys, or customer secrets.

Security Review Questions

Use this checklist when approving a runtime:

Operational Recommendations

• Start every new runtime in smoke mode.
• Install runtimes from versioned packages or approved container images.
• Verify package checksums and release notes before production rollout.
• Use a supervised service, container, Kubernetes workload, n8n workflow, or equivalent production runtime.
• Keep credentials out of shell history.
• Use separate agent identities for orchestrators and execution agents.
• Give execution agents narrow scopes.
• Keep workspace roots narrow.
• Require completion comments for review.
• Validate stop/reload behavior before live execution.
• Monitor online runtimes, active leases, waiting work, and review queue through the Agent Activity widget.

Related Guides

• Agent Orchestration
• Set Up Agent Orchestration
• Assign Work To Agents
• Connect External Agent Runtimes
• Run Codex And Claude Code As External Agents
• External Runtime Packages