Security Posture & Threat Model

Relevant source files

The following files were used as context for generating this wiki page:

• SECURITY.md
• src/main.ts
• src/queue-controller.ts
• README.md
• CONTRIBUTING.md
• biome.json

Introduction

PlanQueue is an OMP (Oh My Pi) harness extension designed to operate as a local TypeScript application running on the Bun runtime. Its primary function is to manage session notes and a FIFO prompt queue for coding agents within a user's local terminal environment. The security posture of PlanQueue is centered on local execution, restricted file I/O, and zero network connectivity.

The scope of the security model covers how the extension interacts with the local filesystem, the registration of Large Language Model (LLM) tools, and the handling of terminal-based data transfers. PlanQueue is designed with a minimal attack surface, collecting no telemetry and making no external network calls.

Sources: SECURITY.md:14-25, README.md:10-15

Local Data Storage and Isolation

PlanQueue maintains a strict boundary for file operations. It predominantly operates within the user's home directory under a dedicated hidden folder.

Filesystem Access

The extension restricts its write operations to the ~/.planqueue/ directory tree. Data is organized by repository, branch, and session ID to prevent cross-context data leakage. While it maintains read-only backward compatibility with legacy directories (~/.free-text/ and ~/.omp-free-text/), all new state mutations are confined to the primary root.

Sources: SECURITY.md:18-20, src/main.ts:13-18, README.md:109-114

Component	Path Pattern	Access Mode	Description
Session Notes	~/.planqueue/{repo}/{branch}/{session-id}.md	Read/Write	Primary storage for prompt queues.
History	~/.planqueue/{repo}/{branch}/{session-id}.history.md	Append	Log of all note changes.
Global Config	~/.planqueue/config.json	Read/Write	User-defined shortcuts and settings.
Legacy Notes	~/.free-text/...	Read-Only	Backward compatibility for older versions.

Data Flow Diagram

The following diagram illustrates how PlanQueue manages data persistence and path resolution.

LLM Tool Security & Agent Interaction

PlanQueue exposes specific tools to the LLM agent (note_add and make_note). These tools are critical points of interaction between the AI agent and the user's local system state.

Tool Restrictions

• Path Isolation: Tools cannot read or write arbitrary paths. They are hardcoded to mutate the active note buffer only.
• Approval Flow: Tools such as note_add and make_note are registered with approval: "write", requiring the OMP host to manage user consent for state changes.
• Input Sanitization: The tools use zod for parameter validation, ensuring that the agent provides correctly formatted strings and structured step objects before any processing occurs.

Sources: SECURITY.md:21-23, src/main.ts:228-250, src/main.ts:312-340

Agent Tool Execution Flow

External Communication and Subprocesses

PlanQueue maintains a "no-network" policy but interacts with the local environment through specific mechanisms.

Terminal Escapes (OSC 52)

The extension implements a clipboard feature using OSC 52 terminal escape sequences. This allows the extension to write the note buffer to the system clipboard without requiring external clipboard utilities. This is a write-only operation directed to the terminal's standard output.

Sources: SECURITY.md:24-25, src/main.ts:60-68

Subprocess Execution

PlanQueue limits its use of shell commands to two specific areas:

1. Git Integration: It calls git rev-parse to determine repository and branch names for path resolution.
2. Herdr Notifications: If the HERDR_ENV=1 environment variable is set, it executes herdr notification show to surface queue alerts to the user.

Sources: SECURITY.md:26-27, src/queue-controller.ts:46-56, src/main.ts:133-142

Threat Model Summary

Threat Category	Mitigation Strategy	Implementation
Data Exfiltration	Zero Network Connectivity	No fetch or socket calls; no telemetry collection.
Path Traversal	Path Anchoring	File I/O is restricted to ~/.planqueue/ via resolveLocation.
Malicious Agent	Capability Restriction	Tools only modify the specific session note; no arbitrary file access.
Clipboard Hijacking	OSC 52 Isolation	Write-only operation; limited to current note buffer content.
Supply Chain	Strict Tooling	Uses Bun for execution, Biome for linting, and strict TypeScript mode.

Sources: SECURITY.md:14-29, CONTRIBUTING.md:15-25, biome.json:17-35

Vulnerability Reporting

The project maintains a policy for private disclosure of security issues. Users are directed to use GitHub's private vulnerability reporting or email the maintainer directly. Public issues for security vulnerabilities are explicitly discouraged to prevent exploitation before a fix is available.

Sources: SECURITY.md:3-12