Tasks (markdown outliner, in development) (part 9)
An eighth agent session type, Define & enrich, is the fuller sibling of Clarify & enrich: it not only sharpens each task's wording, it also captures the context behind it. Like Clarify it is project-launch only — it never appears on a single-task launch (the picker hides it, and the single-task launch schema refuses it, both reading LIST_ONLY_SESSION_TYPES in src/shared/tasks-v2-session-types.ts), because its whole job is to walk the list. The list-launch schema keeps every type. Launch it from a project's "Launch agent…" menu (the launch popup in list mode) and pick Define & enrich.
On this page
What it is
This is part 9 of the Tasks (markdown outliner, in development) page. It carries the next stretch of the material on that page, moved here because a single page is capped at 40,000 characters.
Where to find it
Reach this part through Tasks (markdown outliner, in development) — it lists every part and explains where the feature lives in the product. Everything below is reached from the same place.
How it behaves
Everything below is the behaviour, detail and edge cases that belong to this stretch of the Tasks (markdown outliner, in development) page.
Define & enrich
An eighth agent session type, Define & enrich, is the fuller sibling of Clarify & enrich: it not only sharpens each task's wording, it also captures the context behind it. Like Clarify it is project-launch only — it never appears on a single-task launch (the picker filters it via LIST_ONLY_SESSION_TYPES), because its whole job is to walk the list.
Launch it from a project's "Launch agent…" menu (the launch popup in list mode) and pick Define & enrich. The spawned agent walks the project's open tasks one at a time and, for each task that needs it, prepares two deliverables — then, once you approve that task (it is told to wait for your OK; Omniscio does not block an earlier save), saves both: (1) a clearer rewrite of the task's own text in place (POST /tasks-v2/update), and (2) a durable context note capturing what a future AI would need — what the task really is, why it matters, what "done" looks like, and the specifics that live only in your head (POST /tasks-v2/context/create). It skips tasks that are already clear and well-understood, finishes one task before the next, and — where a task needs only one of the two — does just that one. Where it helps it also offers to break a task into subtasks (POST /tasks-v2/create). It handles an empty / already-clear list ("nothing to do") and a project with more than 40 open tasks (the agent is given only the first 40, in list order, sub-tasks included; it works those and offers to continue) gracefully.
Where Clarify & enrich treats the context note as optional (the clearer description is the point), Define & enrich makes the context note first-class — reach for it when you want every task both legible AND fully briefed for a future agent. Under the hood it reuses the same machinery as Clarify: one main-only preamble (DEFINE_PREAMBLE, never shipped to the renderer), the hidden/visible split, and the existing buildListInterviewPrompt + tasks-v2:launch-list-agent channels — no new IPC channel, Zod schema, DB table, or Labs toggle (it rides the existing Tasks flag). Like the other groomer, the project prompt's hidden background task list carries each task's id, and its session-type-aware footer names both write routes. Still behind the Tasks Labs flag.
Context attachments
Any task can carry a small pile of context attachments — pointers to other sessions, projects, or tasks, plus plain URLs, free-form text/markdown, an attached file, and a linked ContextDock bundle/list — so the work and everything it refers to stay together. The 📎 count chip that appears on any row with attachments is clickable — tapping it pops open a small peek listing those attachments, and clicking any one opens it right there (a URL in your browser; a session, project, task, or file in the app; a note or ContextDock bundle in a read-only content viewer), with a Manage link at the bottom that opens the full pane for adding or removing. On a focused outliner row, the 📎 Context action (in the row's ⋯ overflow menu, or the i key) opens the full Context pane — and the SAME manager is now also a Context tab in the task's two-tab details pane (Cmd/Ctrl+;), so a task's fields and its context are editable in one window. (A task's old single free-form "Context" note was folded into this system as a text entry — nothing is lost, and the row now shows just the 📎 count chip instead of the note's raw @… text.) The pane / tab lets you:
- Attach anything via + Add context → an iconed list of types:
- Session / Project / Task — pick the entity from a searchable list (the task picker spans every list, each option labeled with its list, so you can link to a task in another list).
- URL —
http(s)only (it opens via the OS browser, so other schemes are rejected at the input). - Text / Markdown — a real multi-line editor (plain Enter is a newline; Ctrl/⌘ + Enter or the Add button saves it).
- File — opens your OS file picker and attaches the chosen file by path; the launched agent reads it. (Desktop only — hidden on the mobile web app, where the native picker can't run. The link is to the file where it sits, so moving or deleting the file breaks it.)
- ContextDock — a searchable list of your cached ContextDock bundles/lists (the same curated doc sets you add to projects). Empty / not set up shows a "set up ContextDock in Settings" hint.
- Link a task as "Related" or "Blocks this task". When you link a task (from the add menu or the pencil edit dialog) you choose Related (the default) or Blocks this task, and you can switch an existing link between the two without deleting it. A blocking link shows a small blocks chip. "Blocks this task" means the task you picked has to be done first: link B from A as a blocker and B blocks A.
- See who links to this task. The context pane has a Linked from section listing every live task that links here, each one click away (a click opens that task's details, the same as clicking a linked task); a task that blocks this one is marked waiting on this. Deleted, archived and other-account tasks never appear.
- A blocked task shows a "blocked" chip on its row (hover for "Waiting on N open tasks") for as long as at least one task marked as blocking it is still open; finishing the blocker removes the chip.
- Back out of any step. Every step of the add form ends in a visible Cancel (the type list has a Cancel row), and every step after the type list also has a Back button that returns to the type list. Escape still does the same as Cancel. The URL step has its own Add button (disabled until you type something), the same as the note step.
- Give it a label (optional). Every type has an optional Label field when you add it — leave it blank and it names itself (the entity's name, the URL, or the note's first line, exactly as before); it sits below the main field (URL, text or search) and both fields show a visible caption; fill it (usually the AI does) to give the attachment a clean title, so a task can carry several clearly-labeled contexts instead of one indistinct pile.
- Click an attachment to navigate / open — a session opens that chat, a project switches to it, a linked task opens its own details: it switches to that task's project when it lives in another one, highlights its row and opens the details panel showing the linked task (a deleted target says so instead of dead-ending; a linked task that is snoozed, waiting or hidden as finished says where it is instead), a URL opens externally, a file opens in its default app (with a folder button to reveal it); and a note or ContextDock item opens a read-only content viewer (
TaskV2ContextContentModal) showing its saved text / materialized markdown — there's no target to jump to, so the content itself is the thing you see. - Refresh a ContextDock attachment from its row to re-pull the latest docs (the staleness mirror of a project doc-row refresh).
- Edit an attachment with the pencil on its row, or the Edit button in the read-only viewer — a text/markdown note edits its label AND its body (add more detail without deleting and re-adding); every other kind renames its label. Save with Ctrl/⌘ + Enter or the Save button; ContextDock stays rename-only (its content comes from the bundle).
- Remove an attachment with the trash button. Removal is undoable: a toast appears with Undo that re-adds the item in the slot it held — the list order is the order the agent receives the context in, so an undo puts the attachment back where it was rather than at the bottom (the lightweight Milestone 3 undo — a persisted, cross-restart history is a later milestone).
When the pane cannot load. If the task's attachments fail to load (a transient main-process or database error), the pane says "Couldn't load the context." with a Retry button instead of the "No context attached yet." empty message — so a failed load can never read as "this task has nothing attached", and you never re-add links you already had. The pane also starts fresh each time it is pointed at a different task, so an add form (and anything typed in it) never carries over.
The express path — "Attach a session". Linking a session is the common case, so the right-click menu carries a dedicated "Attach a session" item that opens this Context pane straight at the session picker, skipping the five-step ⋯ → Context → + Add → Session dig. (It used to also be an on-row icon beside Launch agent; that icon was retired to declutter the row — the express capability now lives on the right-click menu, while the longer ⋯ → Context → Session path still works too.) Picking a session creates the same session-kind attachment; an empty session list shows a friendly "No sessions yet". (A session you launched for a task via Launch agent / g is attached to that task automatically now, so you rarely need this for one — see Per-task agent chat.) Under the hood it calls openContextPane(id, { addKind: 'session' }), which seeds a contextInitialAddKind the pane consumes once (a later manual "+ Add context" returns to the normal type picker). Both editable views wire the right-click item via TaskV2RowContextMenu.tsx, so they can't diverge. (TaskV2RowContextMenu.tsx; the pane's optional initialKind lives in TaskV2ContextAddMenu.tsx. See the contract's context-attach-session-icon invariant.)
The reverse — "Attach to task…" from the session side. You can also start from the session: an "Attach to task…" item on a session's menus opens a small task picker, and picking a task creates the very same session-kind link. It lives in two places (both shown only when Tasks is on): right-click a session in the sidebar (single selection), and the open-session header ⋯ menu — that second one renders on mobile too, so it's the phone entry point. The picker is one searchable modal (a full-screen sheet on a phone) with a fixed "Attach to a task" title — the session rides in a chip below it, so a long session name never truncates the title — listing your active tasks grouped under their list header (so same-named tasks in different lists read distinctly). Three redesign touches: a project filter (a scope dropdown — a task has no project of its own, so its project = its list's defaultProjectId; shown only when a task actually belongs to a project, and defaults to the session's own project when that project has tasks, else "All projects"), readable rows (a task whose text is a bare or markdown URL shows a friendly label — "Loom recording", "Shared artifact", else the hostname — with the raw link demoted to a quiet second line, never a chopped URL), and a pinned "New task from this session" action that creates an unfiled task (→ Inbox) titled from the session and attaches it in one click (one Undo removes the whole thing; if the attach fails the new task is deleted again, and if that delete also fails the toast names the leftover task and says to delete it from Inbox, rather than a generic "try again" that would only create a second stray task). Keyboard navigation stays — arrow ↑/↓ to move the highlight over the tasks and Enter to attach, without the mouse (the New-task button sits outside that cycle); it dedups ("Already attached"), confirms with an Undo toast, and reuses the unchanged TASKS_V2_CONTEXT_CREATE (the New-task action also uses TASKS_V2_CREATE) — no new table, channel, or setting. This is separate from a session's taskId (the "launched-from-this-task" binding). See the contract's session-attach-to-task invariant (AttachSessionToTaskPicker.tsx / attach-session-to-task.ts / attach-picker-labels.ts / attach-picker-project-filter.ts).
A row with attachments shows a small 📎 count chip (a quiet, clickable trailing indicator — it opens the attachment peek, see above — on every row that carries context — the focused/selected one included — with the hover action icons revealing to its right rather than covering it; the ⋯ menu's Context action also shows the count as a label), so you can see at a glance which tasks carry context. When a task launches its agent, its attachments are rendered into the launch prompt: the pointer kinds (session / project / task / url / file — a file shows its path + a "read it with your Read tool" hint) become a compact ## Attached context list in which links and file paths arrive whole (never cut short), up to 12 items, with a line pointing at GET /tasks-v2/context/list?taskId=<id> for any beyond that; every attached note is inlined in full under its own ## Attached notes section, bounded at about 32,000 characters per launch, and a note the budget had to shorten is marked and paired with the same route so the agent can read the rest; and each ContextDock item's curated content is inlined in full under a separate ## Reference docs section (capped so one bundle can't balloon the brief) — so the agent boots already aware of what the task points at AND carrying the notes and curated docs. Only the inherited tier (from parent tasks) stays as one-line pointers. The note editor you open from a peek belongs to the Tasks view, not to the row, so an edit in progress (and the text you typed) survives the row scrolling away, being completed, or moving after a change from another window or agent. The peek keeps its own list of attachments and re-reads it every time it opens, so a note edited from the peek shows up the next time you open it, while the full Context pane updates live as attachments change.
Attachments persist in their own task_context_items table (one row per attachment, soft-deleted on remove, fractionally ordered per task). A link to a session or project that the data-retention purge permanently removes is soft-deleted by that purge, so it stops counting toward the 📎 chip and leaves the Context pane instead of pointing at nothing; a project that is only soft-deleted (still restorable) keeps its links. It ships the session | project | task | url | note | file | contextdock kinds. A link — a session, project, task, URL, file or ContextDock item, identified by its kind plus the id it points at — sits on a task only once: adding the same one again returns the row already there instead of a second copy, and the database enforces it with a partial unique index on (task_id, kind, ref_id) over live rows (migration 20261028195639-…), so two creates racing on the main-thread transaction and the DB-worker lane cannot both land. A note, which points at no id, is never deduped, and re-adding a link you removed earlier works because the index covers live rows only. Restoring a task cannot revive two copies of one link either — the duplicate stays removed. The create itself checks the parent task is live before it writes (the table carries no foreign key to tasks_v2, only a referential trigger rejecting a nonexistent id), then appends through the per-task fractional index, excluding the new row's own id so a replayed write lands on the same slot. A ContextDock attachment is materialized at add-time — because the agent has no way to fetch a bundle on its own, Omniscio pulls the content (a bundle → its assembled docs, budget-capped; a list → a titles index) and stores it on the attachment, exactly how a project materializes a linked bundle (Refresh re-pulls it). Deferred to later milestones: the inbox / image kinds (images fold into file), rendering the non-note attachments into the tasks-v2.md mirror (Milestone 6 — a task's notes already appear there as ctx= entries in its metadata comment, refreshed on the next mirror write), and a persisted activity-log + cross-restart undo history (Milestone 5). Tasks accepts the full set of file + contextdock kinds alongside the original five. Like the rest of Tasks, the whole surface stays behind the tasks-v2 Labs gate.
Everything a task's context can do in the app can also be done by scripts and AI agents.
Cascading context — list → subtree → task (M3)
Context is layered and inherited down the tree. Three tiers feed a task:
- the list's master context (the whole-list note),
- a subtree tier — context attached to an ancestor task and marked "also apply to sub-items" cascades down to every descendant, and
- the task's own attachments.
When you add context you can flip an "Also apply to sub-items (cascade)" toggle (it sets the item's inherit flag); cascading items show a "cascades" badge on their row. The context pane shows a read-only "Inherited" section listing exactly what the task inherits and where each piece came from ("From list …", "from <parent task>") — so inheritance is always visible, never a surprise. If an add fails, the add form reopens at the same type with your typed note or link still in it and the cascade toggle as you left it, so a retry adds exactly what you meant.
It is bounded end to end so it can never balloon an AI prompt: the resolver (resolveTaskContext) walks ancestors via a cycle-safe, depth-capped recursive CTE and caps inherited items (12, with a truncated flag); the agent brief truncates each inherited item and caps the section; and the "Right now" prioritizer is fed only a single length-capped shared preamble (the eligible tasks' list master contexts), not per-task inherited lines. The TASKS_V2_CONTEXT_RESOLVE channel (read-only, gated; also a CLI route at GET /tasks-v2/context/resolve) returns the resolved context to the pane, and the same resolver briefs a launched agent (a new ## Inherited context section). Editing a master context invalidates the prioritizer's cached pick — the cache key folds in a content fingerprint of the preamble. The inherit flag lives on task_context_items (migration 20260608052857-…); existing items default to task-only.
Attachments — paste, drop, or attach files to a task
Distinct from the context references above, a task also holds stored file attachments — real copies of images and any other files, shown in an Attachments strip inside the same Context pane. Three ways to add them: paste an image (Ctrl/Cmd+V while the pane is open), drag-and-drop files onto the strip, or the "+" picker (a plain file picker, so a phone offers its camera/gallery). Any file type is accepted, up to 50 MB each in the desktop app, or about 10 MB each when you attach from a paired phone or a browser on web access, and one task holds up to 50 attachments — remove one to add another.
Because they're copies (not links), a pasted screenshot — which has no file on disk to link to — sticks, and an attached file survives you moving or deleting the original. Images render as thumbnails; click one to view it full-size in the in-app lightbox and arrow through the image set. Every other file renders as a name + size pill; clicking a document opens it in your OS default app, while an unknown or program-type file is revealed in its folder rather than launched — so a double-click can never run an attached executable. Remove asks you to confirm, and is undoable — an Undo toast brings the file back, the same lightweight undo the context references above use. The toast lasts a few seconds; after that the app's Undo can still bring the file back while the removal is among your recent undo steps, but that history is cleared when you restart Omniscio. Once it is gone there is no way to bring the file back in the app. The hidden copy is erased from disk 30 days after you remove it, and a shorter or longer Data Retention setting never takes it sooner. While Permanently remove deleted tasks after 30 days (Settings → Tasks → Privacy & retention) is off, removed files are kept. A file whose task is permanently removed goes on the same sweep even if you never removed the file itself: with the task row gone there is nothing left to open it from and no removal left to undo.
When an attachment goes wrong, the message says why — but not the file's name. A save that fails says why — an over-size file keeps its own "too large" sentence, a content/type mismatch keeps its own, and a write the disk refused says so plainly (out of space, or a read-only folder) rather than blaming the file's size or type. Opening or revealing a missing file says the attachment is missing or could not be opened. The messages read "that file" / "that attachment" instead of the file name on purpose: every failure message is also written to the app's log, and a file name such as a medical or legal document's must never land there. If an Undo after a removal cannot bring the file back, you get an error instead of a silent no-op. Each pill also carries a Copy details for support link that puts the file's name, id, on-disk filename and task id on your clipboard, so a "one of my attachments is broken" report can name exactly which row is meant without anyone browsing the app-data folder. The link stays inside its tile: when the tile is too narrow for the whole wording it ends in "…", and hovering it shows the full text.
It works on mobile for images (they load over the same token-gated /attachment/… route the chat uses, and the picker is the phone's file/camera picker); a non-image file can be added and removed from a phone (and the Undo after removing a file works on the phone too, for the account you are signed in to), but opening it in your OS — and the Context pane's Reveal in folder for a file reference — is desktop-only (a phone must not drive your desktop to launch or reveal a file, so over the mobile bridge that open channel is blocked and the pill renders as a plain label instead of a dead tap), and in both light and dark themes. Under the hood the bytes are copied into <userData>/attachments/<taskId>/ — reusing the same hardened store the chat composer uses (the 50 MB cap + type-safety sniff live there) — and recorded in a task_attachments table (migration 20260724042407-…). They stay private by default: an agent launched on the task sees a file only when you tick its Share with agent box, or when Automatically share all files with agents is on in Settings. A shared file reaches the agent as its name, type, size and location (up to the 10 newest), and the agent can open it with its Read tool. See Files attached to a task are private to you unless you share them.
Attached files are kept on this computer only. The automatic backups do not include them — they keep your task list, not the files attached to it — so a lost or failed drive takes the files with it. Turn on the Backup Mirror to keep a copy somewhere else; until it is set up, an inbox card titled "Task attachments are not in your automatic backup" reminds you.
Related
The overview, the other parts, and everything else worth reading next all sit on Tasks (markdown outliner, in development).
Last verified 2026-11-03