Issue Board

The Issue Board is a global view over work stored inside every active Workspace. There is no central issue database: OpenAlice scans each Workspace's .alice/issues/ directory and validates every file independently.

An Issue has two roles:

without when, it is a tracked work item;
with when, the same file self-schedules a headless run of its owning Workspace.

File contract

Each Issue is one file at <workspace>/.alice/issues/<id>.md:

---
title: Pre-market brief
status: todo
priority: high
assignee: "@new"
when: { kind: cron, cron: "30 8 * * 1-5", timezone: America/New_York }
agent: pi
---

Pull pre-market movers and overnight news, write `research/premarket.md`,
then push the report to Inbox. Stay silent when nothing material changed.

The filename stem is the stable Issue id. The Markdown below frontmatter is the canonical What: the complete work definition that humans edit, agents receive, and scheduled runs execute. There is no second prompt field to drift from the document.

Field	Default	Meaning
`title`	required	Human-readable title
`status`	`todo`	`backlog`, `todo`, `in_progress`, `done`, or `canceled`
`priority`	`none`	`urgent`, `high`, `medium`, `low`, or `none`
`assignee`	caller/session dependent	Ownership and scheduled dispatch contract
`when`	absent	Optional `at`, `every`, or `cron` schedule
`agent`	resolved default	Runtime for `@new` or `@workspace` scheduled work

done and canceled are terminal and stop future fires. A successful one-shot at Issue is marked done automatically.

Comments are Markdown records in .alice/issues/<id>.comments.json, not a fragile heading inside the What body. The agent can rewrite the Issue document without erasing the discussion history.

When an Issue has an exact @resumeId owner, a comment from somebody else is delivered asynchronously to that Session. Its final reply becomes another structured comment, while the original records pending, replied, or failed. The note is durable even when delivery fails. Comments on @workspace, @human, or @unassigned remain timeline notes; OpenAlice does not invent an owner merely because somebody commented.

Ownership is explicit

assignee is the only ownership and dispatch field:

Value	Meaning
`@new`	Recruit a new Session on the first fire, then persist that exact Session as the sticky owner
`@workspace`	Recruit a fresh product Session on every scheduled fire
`@resumeId`	Continue one exact, accountable Session every time
`@human`	Human-owned unscheduled work
`@unassigned`	Unassigned unscheduled work

For an agent-created Issue, omitted assignee or @me is resolved server-side to the caller's concrete @resumeId; @me is never stored. An exact Session owner keeps its own runtime, so the top-level agent cannot override it.

@new is useful when recurring work should first recruit a coworker and then keep that coworker accountable. After the first dispatch, the Issue stores the concrete @resumeId; later fires continue that Session. Use @workspace only when every fire should intentionally start fresh.

If an exact owner retires or becomes unresumable, the schedule becomes blocked. OpenAlice does not silently recruit a replacement and pretend conversational continuity. See Sessions & Collaboration.

Timezone-aware scheduling

# Follow the machine running this OpenAlice installation.
when: { kind: cron, cron: "0 9 * * *", timezone: local }

# Follow New York wall time across EST/EDT transitions.
when: { kind: cron, cron: "30 8 * * 1-5", timezone: America/New_York }

timezone accepts local or an IANA timezone. Omitting it preserves machine-local behavior for old files, but new cron Issues should state the clock explicitly. Cron is not an exchange calendar; holidays and early closes remain business conditions in What.

Supported schedule shapes:

when: { kind: at, at: "2026-09-01T13:30:00Z" }
when: { kind: every, every: "1h" }
when: { kind: cron, cron: "0 9 * * 1-5", timezone: local }

Automation health and activity

Issue status describes the work item. A separate derived automation health projection describes whether its schedule is being fulfilled:

not_started, due, running, and healthy are normal states;
interrupted means launcher restart, computer sleep, or a watchdog that woke substantially late cut the work off;
failed means a real timeout, launch error, runtime error, or non-zero process exit and remains until a later success;
blocked means no future fire or an unavailable exact Session owner;
inactive means done or canceled stopped the schedule.

Health is derived from schedule markers, recent runs, and Session availability; it is not another field in Markdown. A successful run may correctly stay silent, so Inbox delivery is not required for healthy automation.

The latest failed or interrupted scheduled run exposes Retry now. Retry re-reads the live Issue and uses the same What, owner, runtime, resume mapping, and 30-minute budget. It does not move the last-fired schedule marker, and the backend rejects duplicate retries instead of creating a retry storm.

The detail view treats the Issue as work rather than an execution dashboard: the main hierarchy is status, priority, owner, What, and one Activity timeline for changes plus conversation. Operational Runs live in a separate collapsible section, and linked Inbox reports remain attributable.

Creation provenance and current ownership stay separate. Normal collaboration uses a comment because the question and answer remain in Activity. Explicit asks are still useful for interrogating the creator or one selected historical run without adding a board comment.

CLI

Agents use the Workspace CLI:

alice-workspace issue list
alice-workspace issue show --id <id-or-title>
alice-workspace issue create \
  --title "Pre-market brief" \
  --what "Write research/premarket.md and push it to Inbox." \
  --when '{"kind":"cron","cron":"30 8 * * 1-5","timezone":"America/New_York"}' \
  --assignee new
alice-workspace issue update --id <id> --status done
alice-workspace issue comment --id <id> --text "Reviewed the first run."

--what writes the canonical Markdown body. Reads aggregate every active Workspace; autonomous writes stay inside the caller's Workspace. Rich Markdown can also be edited directly in the file.

Follow-up commands use provenance rather than guessed agent names:

alice-workspace issue ask --id <id> --creator --prompt "Why was this created?" --await
alice-workspace issue ask --id <id> --run-id <taskId> --prompt "Explain this run." --await

For normal owner collaboration, prefer a durable comment:

alice-workspace issue comment --id <id> --text "What is the next decision?"

Web UI

The global board groups Issues by status. Detail pages provide:

Markdown What editing with autosave;
status, priority, and assignee controls;
schedule and automation-health diagnostics;
comments and owner replies in their stable sidecar;
a chronological change-and-conversation Activity timeline;
a separate Runs section with failure/interruption explanation and manual retry;
linked Inbox reports and exact Session continuation;
Ask creator or Ask run actions when provenance allows them.

Writes change the Workspace working tree; OpenAlice does not auto-commit them.

Execution and safety

The scanner checks due Issues roughly once a minute and dispatches through the normal Workspace runtime. At most eight headless processes run globally; there is no per-Workspace exclusive lock, so prompts and agents must tolerate concurrent edits.

Offboarding blocks while a live run exists. Once a Workspace departs, it disappears from the active scan and its schedules stop. Scheduling never bypasses UTA or Trading-as-Git approval boundaries.

Next Steps

Self-Describing Issues — The concise file-first model.
Automation — Runtime output, run history, and delivery.
Sessions & Collaboration — Exact owners, reconstruction, and signatures.
Inbox — Read and question the reports an Issue produces.

Search Documentation