feat(workflow): attention nudge when a launch workflow parks on a gate

Open
#115 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
javascript, python
Domain
backend, frontend

Research direction

Start with the workflow runner and external event buffer in src/profiles/server/routes/workflow.py and src/profiles/server/routes/instance.py, then trace how the App polls /api/notifications and displays port handoff toasts. Add a gate event when a session newly enters a waiting state, and handle it in the web layer with deduplication and focus checks. Done means the gate draws attention through the requested cues without repeating for the same session and step; the issue names no test files.

Written by the indexing model from the issue text.

Description

enhancement

Problem

When a launch triggers workflow hooks containing ask:/notify: gates, the session parks in waiting_ask/waiting_notify until the user answers. Users who trigger launches via barcode scans or keyboard shortcuts are frequently focused in another application when the gate appears — ProFiles sits in the background with the runner modal open and nothing draws them back. Interactive sessions are kept indefinitely (the TTL purge only drops terminal sessions), so a missed gate can block the rest of a workflow for as long as the app runs.

Evidence

  • The only way forward is the respond route; src/profiles/server/routes/workflow.py:397-643. The purge at src/profiles/server/routes/workflow.py:90-96 explicitly keeps interactive sessions (Drop terminal sessions past the TTL (interactive ones are kept)).
  • A general UI event poll channel already exists and is already polled by the app for port-handoff toasts: GET /api/notifications at src/profiles/server/routes/instance.py:74 (state.external_events_after(after)).
  • No event is recorded when a session enters a waiting state, and no OS-level attention mechanism (toast, document.title flash, notification) exists anywhere in the web layer today.

Proposed approach

  • Server: when the session runner parks on waiting_ask / waiting_notify / notice, push an event into the existing external-events buffer (same channel the port handoff uses), carrying session id + gate kind.
  • Web: the App-level notifications poll already runs — on a gate event, show a toast, flash document.title, and fire a Web Notification where the environment permits. Fire only when the gate is newly reached (dedupe per session+step), and skip when the document has focus.
  • Desktop (optional stretch): a pywebview-specific attention request kept inside profiles.desktop, per the AGENTS.md layering rules (presentation layer only).
  • Scope S-M. No breaking change — additive event + UI behaviour.

Alternatives considered

  1. Auto-timeout on gates — changes workflow semantics and could auto-launch or auto-skip against the user's intent; rejected.
  2. Sound-only cue — poor accessibility and lost on muted systems; toast + title flash is quieter, testable headlessly (vitest), and composes with the existing toast component.

Proposed during automated enhancement scan 2026-11-04

Dominant language
Python
Stars
1
Forks
1
Avg merge
4h 46m
Merged PRs (30d)
55

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from falbany/ProFiles

All issues in falbany/ProFiles

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.