The setup marker saves the profile setup was made from. After that
profile was renamed, the saved name pointed at a missing directory, so
start_chat and reset targeted nothing. The owner now resolves through the
rename history (profile.yaml previous_names) that rename already records.
Setup started from a named profile handed its first task to default once the setup backend was active: both get_hermes_home() and the launch home named the setup profile, and _user_home fell back to a hard-coded default. The setup marker now records the profile setup was made or reset from, and the handoff uses it. Greptile P1 on #134209.
release_setup_copy removed project and catalog from every copy, so a toolset the
user had disabled before setup cloned their profile came back enabled. Setup now
records in its marker which toolsets it disabled itself (setup_disabled_toolsets,
kept across a reset), and a copy undoes only those, reading the source profile's
marker. The bookkeeping key stays out of the onboarding state the app reads.
release_setup_copy removed only the cli toolset grant; the project and catalog
toolsets the setup profile disables and its deferred-tool list stayed in the copy.
It now undoes all three tool limits _write_setup_config adds, keeping the user's
own disabled toolsets.
During onboarding the ambient backend is the setup profile's own pooled backend, so
its launch home is the setup profile too. reset_setup_profile then picked the setup
profile as the skills source, emptied its skills dir and copied from the now-empty
dir. primary_profile had the same fallback and named the setup profile as the
handoff target. Both now take the first home that is not the setup profile
(ambient, then launch, then default).
The setup profile's grant lives in its config.yaml (platform_toolsets.cli), and
clone, clone-all, import and distribution install copy config.yaml while dropping
only the marker, so setup_choose and start_chat leaked into an ordinary profile.
Every copy path now goes through setup_profile.release_setup_copy, which drops the
marker and, when the source was the setup profile, the cli grant
(atomic_config_replace).
onboarding.state reported intro=unseen for every install without a setup
profile, so a user who had already used Hermes got the guide as soon as
the guest flag turned on.
On first launch (no setup profile yet), settle_returning_user() latches
onboarding.seen.setup_intro in config.yaml when the install has a session
row in state.db or a user-made profile, and read_state() reports 'seen'
from that latch. A fresh boot creates neither, so it stays 'unseen'.
Reset run from the setup chat copied the setup profile's own skills onto itself after emptying them; it now
copies from the launch profile, the rule primary_profile() already uses. A /initiate-setup re-sent into a
stalled chat replaced the cards file and dropped the picks; it now refreshes the facts and keeps the answers.
The setup chat no longer scans the computer. The collector, its host_facts.py
hook, the inline-shell setting on the setup profile, the ${HERMES_PYTHON}
skill token and the insights/ cache are gone.
The first /initiate-setup turn now sends the skill plus one JSON block that the
model reads as it is: machine basics (OS, release, architecture, CPU, RAM, GPU
class, vendor, WSL, container), machine_kind, has_nvidia_gpu, is_spark,
suggested_name and locale, beside the session keys. A key that was not
measured is left out.
The non-scan parts of host_facts.py (account name, locale, Spark detection,
the fork card, the NVIDIA and Blender tasks, the handoff text) move to
agent/initiate_setup_facts.py and are imported normally instead of loaded by
file path.
With a user key the setup chat inherited the default effort, so the turn
before the handoff spent 100 s writing 3,226 tokens (12 KB of reasoning)
while the chat showed only a timer. The free tier already ran at minimal.
* feat(setup): the backend fills the tour and fork cards and preselects scanned apps
The welcome model fills only the required parameters of setup_choose, so
cards that needed options arrived as bare text boxes in play 4. options is
now required ([] means the app's list, or free text for a question).
Two new kinds, tour and fork, take their rows from the backend whatever
the model sends. The fork rows come from the facts the /initiate-setup turn
embedded, recorded next to the setup state; "Something else" on a
machine-first fork opens the rest in the same call. The connectors and
plugins cards start with the apps the scan saw in use, and Blender when it
is here, already picked. The result names a picked row (label), so the
settled card shows labels for rows that are not in the call's args.
* fix(setup): the setup skill answers honestly about the scan and always reaches a handoff
Card lines carry options and use the app-owned tour and fork kinds. When
asked what Hermes knows, the model answers from the facts and names the
scan instead of denying it. A skipped fork goes to a first-task card built
from the scan, a second skip offers one concrete task, and a card left for
an off-flow question is re-sent. Dead fork-building and fallback text is
cut, which keeps the skill under 25 KB.
* fix(setup): card facts per setup conversation; the backend steers each beat and carries the handoff
The saved card facts were one file per setup profile, so a second
/initiate-setup overwrote the first conversation's fork rows. They are now
keyed by the session id under the bound Hermes home, and setup_choose reads
its own session's block. A fork card with no recorded facts (skill loaded
through the inline-shell hook) collects them fresh.
setup_choose now returns `next` for the flow's following step (the next
card's exact arguments, the skip ladder from the fork on, a re-send of the
pending card after typed off-flow text) and, from the fork, `handoff`: the
message parts and the plan, cut to this machine, from templates/handoff.md.
That moves about 6 KB of handoff and plan text out of the first turn.
Rows the model sends for tour, fork and the new machine_use kind are
dropped before validation, so a malformed copy can no longer fail the card.
The connectors and plugins cards are always multi-select, so preselected
rows are never lost to a single-select confirm. The off-desktop voice rule
is back in the skill.
* docs: regenerate the initiate-setup skill page
* feat(initiate-setup): one "I noticed" line before the fork shapes the first tasks
* fix: userscan tmux and zellij socket probes pass the /tmp literal check
The four lines read where tmux and zellij put their sockets (and, on macOS,
measure the user's own temp dir). The POSIX fallback for those directories
is /tmp, so the literal is the fact being probed, not a scratch path. Mark
each line so the blocking lint step in lint.yml passes.
* fix: setup-profile and start_chat RPCs no longer block the RPC reader
onboarding.ensure_setup_profile / ensure_setup_session / reset_setup_profile
can run create_profile (a skill-tree copy), state.db writes and the first
import of the setup scanner. session.start_chat creates a session and runs
prompt.submit. Inline on the reader thread they left session.interrupt and
approval.respond unread in the pipe, the failure the _LONG_HANDLERS comment
names. profiles.create was already on the list for the same reason.
* fix: userscan children run with stdin closed and the served profile's env
The /initiate-setup builder runs the user scan on a backend thread, so
every child the scan spawned inherited the JSON-RPC stdin pipe (#14036)
and the launch profile's os.environ. HostAccess.run, copy_locked and the
PowerShell batch now pass stdin=subprocess.DEVNULL, and every spawn takes
its env from HostAccess.child_env(). host_facts passes
served_profile_child_env() into the run; the standalone run.py keeps the
process env.
check_subprocess_stdin.py now scans optional-skills/: the backend loads
initiate-setup's scripts in-process. The nested-dir skip matches paths
relative to the context dir, so a skill's own scripts/ folder is in
scope. Three model-run optional-skill scripts it flagged get stdin closed.
* refactor: split the userscan spec modules over 2,000 lines by topic
Six spec modules under initiate-setup's userscan passed the 2,000-line
gate. Each keeps its shared helpers and first families; the rest move
verbatim into <stem>_<topic>.py siblings that import the helpers they
use from the base module:
apps_dev -> apps_dev_agents, apps_dev_devenv
browser_files -> browser_files_comms, browser_files_content
usage_gaming -> usage_gaming_games, usage_gaming_hardware
linux_system -> linux_system_security, linux_system_hardware
linux_apps -> linux_apps_dev, linux_apps_browser, linux_apps_files
darwin_apps -> darwin_apps_dev, darwin_apps_browser, darwin_apps_files
linux_system keeps health and usage: install_age reads usage's _wtmp and
usage reads health's _kdump_dirs. References through the ad./bf./ug.
aliases point at the module that now defines the name. specs/__init__
imports each sibling right after its base, so per-OS registration order
and the registry keys stay the same.
No behaviour change: `run.py --list` is byte-identical before and after,
and a temp-home scan under --os darwin/linux/windows gives the same fact
statuses, errors and insights.
* fix: the setup scan never patches process globals or sys.path in the backend
The /initiate-setup builder runs the user scan on a backend thread. It put
the scanner dir at sys.path[0] of the backend (so a top-level `run` or
`userscan` import anywhere resolved to the scanner), and it loaded
host.py's deny_reads_under (swaps builtins.open, io.open, sqlite3.connect
and subprocess.Popen) and override_env (rewrites os.environ HOME and
HERMES_HOME) into the backend's import graph.
- userscan/cli.py now holds override_env, the read guard, the aggregate
HostAccess and scan_accounts. Only run.py imports it; runner.run() no
longer retargets os.environ (overrides stay l0 data), and run.py applies
override_env around run() for --home and friends.
- The package uses relative imports, and host_facts loads it once per
process as initiate_setup_userscan, without touching sys.path.
Live: after an in-process scan sys.path, os.environ and the four patched
callables are unchanged and no top-level userscan module exists (before:
sys.path[0] was the scanner dir and userscan.host was importable).
`run.py --list` is unchanged; --all-users and --home give the same output.
* refactor: userscan runner runs each layer as a named phase
runner._run was one closure-heavy function at cyclomatic complexity 66.
Its state moves onto a small _Pass object whose run_l1 / run_l2 (with
_run_python_l2) / run_l3 methods each hold one layer, moved verbatim;
_run composes them and builds the output. Highest CC in the file is now
21 (run_l3).
No behaviour change: temp-home scans under --os darwin/linux/windows give
the same fact ids, statuses, methods, tiers, coverage, insights and
output keys as before.
* chore: name the setup intro flag writer, document gui_tour presets, trim media.ts
- hermes_cli/setup_profile.py::mark_seen becomes mark_intro_seen. It
writes the setup profile's intro state; agent/onboarding.py::mark_seen
flips a config.yaml hint flag, and tui_gateway uses both. The RPC name
onboarding.mark_seen is unchanged.
- tools-reference: gui_tour's `start` without `steps` runs the built-in
tour (`preset` quick or full, default full).
- apps/desktop/src/lib/media.ts: drop the blank line at EOF (git diff --check).
* docs: describe the setup chat's automatic machine scan
The scan runs without a consent step when the desktop app creates the
setup profile (the owner kept it automatic). The desktop user guide now
says where it runs (the backend's machine), what it reads (T1: counts and
categories; finer values are dropped before storage), what reaches the
model (the derived fact block in the first setup message, sent to the
setup chat's inference provider) and where the cache lives
(insights/profile.json in the setup profile's home, 0600, 24 h).
The skill's own docs page is generated from SKILL.md, which is the model's
prompt, so the user-facing text lives in the desktop guide.
* fix: overlapping setup-profile RPCs no longer race on the RPC pool
ensure_setup_profile, ensure_setup_session and reset_setup_profile moved off the reader thread, so two kickoffs could overlap: both saw no setup profile, and the losers failed on the half-made profile (5 of 6 barrier-started calls returned ENOENT), or both saw an empty setup chat and seeded it twice. One module lock restores the one-at-a-time order; the prescan stays outside it.
* fix: the Linux locale probe reads date formats in a child, not via setlocale
locale.user ran setlocale(LC_TIME) on the scan thread inside the backend. setlocale is process-wide and not thread-safe, so strftime in other session threads briefly used the user's LC_TIME. The probe now runs 'locale d_fmt t_fmt' under LC_ALL=<locale> through HostAccess.run (new env overlay on child_env), after checking 'locale -a', because locale prints C formats for a locale that is not installed.
* docs: link the setup scan from the /initiate-setup and onboarding references
The desktop guide's scan section now says which search-engine names are kept and that the scan runs in the CLI and the gateway too. The /initiate-setup row and the profile_build bullet link to it.
* fix(setup): manage_catalog leaves the setup chat; installs go to the caller's profile
- The setup profile disables the catalog toolset. The desktop session
folded it in as a client-surface toolset, so manage_catalog was still on
the setup chat's eager tool list.
- Delete default_target_profile: a catalog install and search target the
calling chat's own profile, the setup profile included.
- /initiate-setup still needs "the launch profile when run from the setup
home"; that moves to hermes_cli.setup_profile.primary_profile().
- The manage_catalog description and the reference docs drop the setup
chat exception.
* feat(setup): drop setup_choose intent; apps and plugins cards say they set up later
- setup_choose loses `intent` (the now / when needed / just note it choice)
in the tool, the wire contract and the cards. The result is
{outcome, picked}. Contracts regenerated.
- The apps and plugins pickers carry one footnote, "We'll set these up
when you start.", replacing the plugins-only "Nothing connects or
installs yet" note. Other locales translated; the desktop key list is
regenerated (it was also behind en.ts on appTour and sharedMetrics).
* fix(desktop): an install card stays drawn when a connect card follows it
The renderer keeps one connection operation per session. When a turn asks
twice (a manage_catalog install card, then a manage_connections connect
card), the second operation replaced the first in the store, and the
settled install card fell back to a plain tool row.
A settled operation that the next one replaces now moves to a store keyed
by its tool call, and the catalog and connector cards read their own row's
operation from there. Both cards stay stacked in the turn.
* fix(setup): setup_choose inline calls stop passing intent; /initiate-setup reads the launch home at call time
The inline executor still mapped intent into setup_choose_tool, which no
longer takes it, so every desktop setup_choose call raised TypeError.
primary_profile now gets server._launch_home() instead of the import-time
_hermes_home.
* fix(desktop): keep one card per kind: the latest install card and the latest connect card
The replaced-operation cache kept every settled operation by tool call, so
consecutive manage_connections calls drew one connect card each. It now
keeps, per session, only the settled operation of the other kind (install
vs connect) that the current one replaced. An install card and a connect
card stay stacked in either order, and a later call of the same kind still
takes over its card. clearConnectionRequest clears both caches, and the MCP
setup card reads the same per-row selector, so sessionConnectionRequest is
gone.
* initiate-setup: the model starts after the accent answer; no theme or install beat, no intent
The app will play the welcome, name and accent (P18), so the skill's own
work starts at the apps card and is shaped by the scan and what the user
says. The theme beat, the install beat and every setup_choose intent are
gone. The setup chat connects only apps the user asks to connect now; the
handoff message asks the task chat's first turn for one manage_catalog
install and one manage_connections connect for the picks the task needs.
Round-6 literal card lines and acknowledgment rules are ported without
intent. The Voice section is cut: SETUP_SOUL is the one persona and gains
the style rules it lacked. catalog_evidence, desktop_plugins_root and the
interface plan are dropped because the builder never sends them.
SKILL.md goes from 39,255 to 24,955 bytes; MAPPING.md and the generated
skill page follow.
* initiate-setup: fix review findings
- Regenerate the skill page (it was stale).
- Handoff part 4 goes only with an install or connect list; each clause
drops with its empty list.
- Layout beat keeps one light opinion.
- Off desktop: persona line, no manage_catalog install clause, plugin
install command for the user.
- A rejected start_chat retry keeps profile.
- The builder sends setup_completed_at; the skill does not replay setup
after a handoff.
- The setup profile disables the catalog toolset, so the desktop
fold-in no longer adds manage_catalog.
- host_facts rejects handle-like display names (p14, CD_01.05).
- No forced 'Two seconds' line; MAPPING.md has no intent references.
The setup profile gets the connections toolset, so manage_connections is
on its eager tool list next to setup_choose, start_chat, apply_layout,
gui_tour and manage_catalog. The skill connects only the apps the user
asks to connect now; the other picks still wait for the task chat.
When start_chat runs from the marked setup profile's chat and opens the
new chat in another profile, the backend now writes completed_at and
intro: seen into the setup profile's onboarding marker. The write goes
through a new hermes_cli.setup_profile.mark_completed(), next to
mark_seen(), so onboarding.state reports completed_at unchanged.
Calls from any other profile write nothing. A call from the setup
profile into itself writes nothing. Rejected calls write nothing. A
reset of the setup profile still writes the fresh state, so it clears
completed_at.
The tools reference row for start_chat states the new effect.
Linear: NS-1018
The merged Wave A and skill PRs landed without CI: the generated skill docs did not list initiate-setup, the shared-metrics v3 schema lacked the start_chat toolset, and the setup-profile marker read was BOM-intolerant on Windows.
Sid's decision: the setup chat has setup_choose, start_chat,
apply_layout, gui_tour and manage_catalog, and nothing else.
- platform_toolsets.cli lists "start_chat" again. The toolset lands
with P14; until then it is an unknown name that the desktop resolver
skips.
- agent.disabled_toolsets drops "catalog" and adds "project". After
P11, manage_catalog lives in the client-surface catalog toolset, so
disabling it removed a tool the setup chat needs. desktop_project is
not one of the five.
- gui_tour leaves the tools.tool_search.defer list, so all five stay
eager.
desktop_ui cannot be disabled (_with_session_toolsets keeps it) and no
per-tool disable exists. Its other tools stay on the defer list, behind
the tool_search bridge.
Check follow-ups.
- onboarding.ensure_setup_session is back. It creates or finds the
setup chat by title, so every call returns the same chat and whether
it is empty. It takes optional seed messages and writes them only
into an empty chat.
- The kickoff now seeds through it instead of its own titled
session.create, and adopts a title hit only when it has messages. An
empty row no longer breaks the title lookup; the kickoff seeds it.
- The setup config no longer lists "start_chat" in
platform_toolsets.cli. The toolset does not exist on this branch, so
config validation and CLI startup warned about an unknown toolset.
Review follow-ups.
- The setup config now writes agent.disabled_toolsets with "catalog"
(merged with the cloned list), so the client-surface catalog toolset
does not fold into the setup chat once it exists.
- It pins agent.coding_context to "off", so a cloned "focus" posture
cannot swap in the coding toolset in a code workspace.
- It replaces tools.tool_search instead of merging into the cloned
block. A cloned "enabled: off" no longer turns the defer list off,
and the bool form no longer raises and deletes the new profile.
- onboarding.ensure_setup_session is removed. Nothing called it, and
its empty row would break the kickoff's title lookup. It returns
with the intro view, which can seed an existing chat.
- requestDesktopOnboarding and the free-tier ready screen wait until
the gate has read onboarding.state, so they no longer see "idle"
before the guide starts.
The setup profile's marker now holds the onboarding state:
{intro: unseen|seen, failed_starts: 0..3, completed_at?}. New RPCs read
and change it: onboarding.state (plus eligible, read from
HERMES_GUEST_ONBOARDING only), onboarding.record_failed_start (the third
failure marks the intro seen) and onboarding.mark_seen.
onboarding.reset_setup_profile clears it. onboarding.ensure_setup_session
creates or finds the setup chat by title and writes its row at once, so
every call returns the same chat. The renderer does not call it yet; the
kickoff keeps its seeded create until the intro view lands.
The setup profile's config.yaml is now written, not appended to:
platform_toolsets.cli = [setup, start_chat, no_mcp], a hand-written
tools.tool_search.defer list that keeps apply_layout, setup_choose and
start_chat eager, and display.show_reasoning = false. Creation and reset
no longer copy MEMORY.md and USER.md from the launch profile, because
the built-in store loads them even with the memory toolset off.
The renderer no longer keeps the phase in localStorage. The gate seeds
from onboarding.state, Skip and the app handoff mark the intro seen, and
a failed start is counted instead of saved as "skipped" forever. A start
without inference turns the guide off for this launch and counts
nothing. The duplicate PERSONA prompt block is gone; SOUL.md is the only
copy.
Review follow-ups to the role deletion.
- The setup toolset reached any surface that read platform_toolsets.cli
(classic CLI, hermes -z, kanban workers), and "all" / "*" / a None
selection pulled manage_catalog into every profile. Now "all" skips
toolsets in TOOLSET_SESSION_PLATFORMS, so they arrive only when named,
and agent tool loading drops their tools unless the agent's own
platform is listed (toolsets.session_platform_tool_drops, applied in
_load_tools and in the MCP refresh / pin restore paths). The name
filter in tui_gateway's _with_session_toolsets is gone: one gate.
- The focus coding posture replaced the configured list, so the guide in
a code workspace lost the setup toolset. The posture path now carries
the config's session-gated toolsets.
- ensure_setup_profile deletes the new profile if a step after
create_profile fails, so a retry does not leave unmarked orphans.
- Desktop handoff recovery waits until the active session is bound to
the selected guide chat, so it records the guide's profile and runtime
id after the gateway swap, not the previous profile's.
- Delete the renamed catalog test (lane rule) and correct the reference
docs.
Linear NS-1014.
The setup toolset was reserved for `role: setup` in profile.yaml, resolved by
toolsets.profile_role_toolsets, and stripped from every other profile in
model_tools._select_tool_names. Onboarding also wrote that role into a user's
existing unmarked hermes-setup profile and adopted it, and cloned the literal
default profile.
Now there is no role anywhere. The setup profile carries a dot-file marker
(.setup-profile.json) at its root, and onboarding finds it by that marker. A
user's own unmarked hermes-setup is never touched: onboarding makes
hermes-setup-<word> instead. The new profile is cloned from the launch
profile, and its own config enables the setup toolset in
platform_toolsets.cli. The session resolver keeps the toolset only for
desktop sessions (toolsets.TOOLSET_SESSION_PLATFORMS). Copies (clone-all,
import, distribution install) drop the marker, as they dropped the role.
The role field also leaves ProfileInfo, the profiles.list and dashboard rows,
the onboarding.ensure_setup_profile result, the gateway contracts, and the
desktop ProfileInfo type. The desktop handoff recovery check no longer gates
on the roster role; the guide handoff receipt keyed by the stored session
already identifies the guide session.
Linear NS-1014.
* refactor(desktop): remove the onboarding intro cinematic and the guided-onboarding tests
The guided first run now opens straight into the guide: the gate's
`cinematic` phase becomes `pending`, and OnboardingChatGate owes the guide
on mount (the old HERMES_SKIP_INTRO path, now the only path). Removes the
native intro window, its IPC bridge, the `?win=intro` renderer, its assets,
and the skipIntro launch flag. Deletes the guided-onboarding test files ahead
of the rewrite, plus the reset helpers only they called.
* refactor(onboarding): strip comments from the guided-onboarding modules
Clears comments and docstrings from the guided-onboarding files ahead of
their rewrite, desktop and backend. Lint and type pragmas stay. No code
changes.
* feat: setup profile is minted by the backend and found by role, not by name
The guided onboarding runs in a profile the desktop used to create itself
(profiles.create with a soul, "already exists" treated as success) and
recognise by the literal "hermes-setup". The upcoming setup toolset grants
catalog installs to that profile, so the marker that grants it must be
written only by the backend.
- profile.yaml carries `role: setup`; read_profile_meta / write_profile_meta /
ProfileInfo know it; profiles.list and GET /api/profiles report it.
- hermes_cli/setup_profile.py: ensure (find by role, adopt a pre-role
hermes-setup dir, else clone default + soul + role) and reset (soul,
memories, skills back to the created state, in place). The soul text moves
here from the renderer.
- tui_gateway/methods_onboarding.py: onboarding.ensure_setup_profile and
onboarding.reset_setup_profile. Neither takes a name; profiles.create and
profiles.configure already reject `role` (unknown key, 4000).
- Copies never inherit the role: --clone-all, profile import, and a
distribution that ships profile.yaml drop it.
- setup.status for a named profile reports `ready` once the boot bootstrap
settled. Since one host backend serves every profile (#118246) the
desktop's setup-profile probe lands on this branch, which never set
`ready`, and the kickoff waited forever.
- Desktop: SETUP_PROFILE, ensureSetupProfile(profiles.create) and
composeSetupSoul are gone. store/setup-profile.ts holds the name the
backend returned (or the roster's role row after a relaunch); kickoff,
handoff and the build card use it. The dev reset calls the reset RPC.
* fix: write the setup soul as bytes so Windows keeps \n line endings
* refactor(desktop): drop the renderer's setup-profile store; the backend is the only owner
Kickoff reads the name straight from onboarding.ensure_setup_profile and records it on
$setupSession, which every later step already carries. The handoff recovery check reads
the roster row's role. No renderer module holds a setup-profile name or a fallback lookup.
