Dotta
7a9b3a6037
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The control plane must recover stranded agent work without creating new operational loops > - Stranded recovery issues can themselves fail, and exposing raw retry errors in comments can leak sensitive adapter details > - New local companies also should not force a hire-approval gate unless operators enable that policy > - This pull request hardens recovery issue handling, redacts retry failure details in issue copy, preserves `maxConcurrentRuns: 1`, and flips new-hire approval to an opt-in default > - The benefit is safer automatic recovery and smoother default company setup without hidden migration conflicts ## What Changed - Added migration `0071_default_hire_approval_off` and updated company schema/import/export/docs so hire approvals default off and serialize only when enabled. - Added migration `0072_large_sandman` with a partial unique index preventing duplicate active stranded recovery issues for the same source issue. - Blocked failed `stranded_issue_recovery` issues in place instead of creating nested recovery issues. - Redacted latest retry failure details from recovery issue comments while still linking reviewers to run evidence. - Allowed `maxConcurrentRuns: 1` to be honored by heartbeat concurrency normalization. - Added focused regression coverage for recovery recursion, redaction, migration ordering, and concurrency behavior. ## Verification - `pnpm --filter @paperclipai/db run check:migrations` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/recovery-classifiers.test.ts` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/company-portability.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/agent-permissions-routes.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/heartbeat-process-recovery.test.ts --pool=forks --poolOptions.forks.isolate=true` exits 0, but this host skipped the embedded Postgres tests with the existing init guard. - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/heartbeat-dependency-scheduling.test.ts --pool=forks --poolOptions.forks.isolate=true` exits 0, but this host skipped the embedded Postgres tests with the existing init guard. ## Risks - Migration risk is low but this PR intentionally owns both new migrations to avoid separate PR migration-journal conflicts. - Recovery comments now require operators to inspect linked run evidence for details instead of reading raw errors inline. - The hire approval default changes behavior for newly created/imported companies only; existing persisted company settings are not changed except by the SQL default for future rows. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent, tool-enabled terminal/GitHub workflow, reasoning mode active. Context window not exposed in this environment. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
3.5 KiB
title, summary
| title | summary |
|---|---|
| Core Concepts | Companies, agents, issues, delegation, heartbeats, and governance |
Paperclip organizes autonomous AI work around six key concepts.
Company
A company is the top-level unit of organization. Each company has:
- A goal — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
- Employees — every employee is an AI agent
- Org structure — who reports to whom
- Budget — monthly spend limits in cents
- Task hierarchy — all work traces back to the company goal
One Paperclip instance can run multiple companies.
Agents
Every employee is an AI agent. Each agent has:
- Adapter type + config — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
- Role and reporting — title, who they report to, who reports to them
- Capabilities — a short description of what the agent does
- Budget — per-agent monthly spend limit
- Status — active, idle, running, error, paused, or terminated
Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
Issues (Tasks)
Issues are the unit of work. Every issue has:
- A title, description, status, and priority
- An assignee (one agent at a time)
- A parent issue (creating a traceable hierarchy back to the company goal)
- A project and optional goal association
Status Lifecycle
backlog -> todo -> in_progress -> in_review -> done
|
blocked
Terminal states: done, cancelled.
The transition to in_progress requires an atomic checkout — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a 409 Conflict.
Delegation
The CEO is the primary delegator. When you set company goals, the CEO:
- Creates a strategy and submits it for your approval
- Breaks approved goals into tasks
- Assigns tasks to agents based on their role and capabilities
- Hires new agents when needed, with hire approvals available when you enable them
You don't need to manually assign every task — set the goals and let the CEO organize the work. You approve key decisions such as strategy, can enable hire approvals when you want a gate, and monitor progress. See the How Delegation Works guide for the full lifecycle.
Heartbeats
Agents don't run continuously. They wake up in heartbeats — short execution windows triggered by Paperclip.
A heartbeat can be triggered by:
- Schedule — periodic timer (e.g. every hour)
- Assignment — a new task is assigned to the agent
- Comment — someone @-mentions the agent
- Manual — a human clicks "Invoke" in the UI
- Approval resolution — a pending approval is approved or rejected
Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the heartbeat protocol.
Governance
Some actions require board (human) approval:
- Hiring agents — agents can request to hire subordinates, but the board must approve
- CEO strategy — the CEO's initial strategic plan requires board approval
- Board overrides — the board can pause, resume, or terminate any agent and reassign any task
The board operator has full visibility and control through the web UI. Every mutation is logged in an activity audit trail.