Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
feat(cli): concise help and one-step Session titles (#2980)
Call White6f2bf0bb3b62
diff --git a/core/prompts/session-title.md b/core/prompts/session-title.mdindex 54f8dc946..dbc274d19 100644--- a/core/prompts/session-title.md+++ b/core/prompts/session-title.md@@ -1,8 +1,5 @@## Session Title-Once this Web conversation's topic is clear, silently set one concise, human-scannable Session title without waiting for the user. First inspect:-`vibe session get`+Once this Web conversation's topic is clear, silently set one concise, human-scannable Session title without waiting for the user:+`vibe session update --title "<short title>" --if-untitled`-If `metadata.title_source` is `user` or `agent`, leave the title unchanged. Otherwise set it once:-`vibe session update --title "<short title>"`--Do not mention the update unless asked. After setting it, do not rename it again.+It keeps a title the user or an Agent already set. Do not mention the update unless asked. After setting it, do not rename it again.diff --git a/docs/CLI.md b/docs/CLI.mdindex 47a87ace5..c46fe1615 100644--- a/docs/CLI.md+++ b/docs/CLI.md@@ -511,6 +511,7 @@ vibe session list --page 2 --limit 50 # request page 2 with 50 rows (at most 1vibe session get # inside an Avibe Agent shell, the caller Sessionvibe session get --session-id sesk8m4q2p7x # full detail for another Sessionvibe session update --title 'Release review' # inside an Avibe Agent shell+vibe session update --title 'Release review' --if-untitled # keep a title a user or Agent setvibe session update --session-id sesk8m4q2p7x --title '' # clear the titlevibe session update --session-id sesk8m4q2p7x --hidden # background-only; --visible promotes itvibe session queue list --session-id sesk8m4q2p7x # queued messages in FIFO order@@ -519,7 +520,11 @@ vibe session send-now --session-id sesk8m4q2p7x # promote the exact```Every command except `list` acts on one Session: `--session-id`, or the caller-Session inside an Avibe Agent shell (see [Grammar](#grammar)). `--type` accepts+Session inside an Avibe Agent shell (see [Grammar](#grammar)). With `--if-untitled`,+`update --title` writes only when no user or Agent has titled the Session; an+automatic title still counts as untitled. The check and the write are one+transaction, so a concurrent rename is never overwritten, and `updated: false`+reports that the existing title was kept. `--type` acceptsa platform id: `avibe` (Web/Workbench), `slack`, `discord`, `telegram`, `lark`,`wechat`. For richer filtering — by agent, time range, message content, orcross-table joins — use `vibe data query`.diff --git a/docs/CLI_ZH.md b/docs/CLI_ZH.mdindex 674a3a759..110787330 100644--- a/docs/CLI_ZH.md+++ b/docs/CLI_ZH.md@@ -403,6 +403,7 @@ vibe session list --page 2 --limit 50 # 第 2 页,每页 50 条(最多 100vibe session get # 在 Avibe Agent shell 内查看调用方 Sessionvibe session get --session-id sesk8m4q2p7x # 其他会话的完整明细vibe session update --title 'Release review' # 在 Avibe Agent shell 内+vibe session update --title 'Release review' --if-untitled # 保留用户或 Agent 已设置的标题vibe session update --session-id sesk8m4q2p7x --title '' # 清空标题vibe session update --session-id sesk8m4q2p7x --hidden # 只在后台;--visible 恢复显示vibe session queue list --session-id sesk8m4q2p7x # 按 FIFO 顺序列出排队消息@@ -411,7 +412,9 @@ vibe session send-now --session-id sesk8m4q2p7x # 提升精确的```除 `list` 外,每个命令都作用于一个 Session:`--session-id`,或在 Avibe Agent shell-内默认的调用方 Session(见 [语法](#语法))。`--type` 取平台 id:`avibe`(Web/Workbench)、`slack`、`discord`、`telegram`、`lark`、`wechat`。需要更高级的筛选——按 Agent、时间段、消息内容或跨表联查——请使用 `vibe data query`。+内默认的调用方 Session(见 [语法](#语法))。加上 `--if-untitled` 时,`update --title`+只在用户或 Agent 尚未设置标题时写入,自动生成的标题仍视为未命名;检查与写入在同一个事务内,+不会覆盖同时发生的重命名,`updated: false` 表示保留了原标题。`--type` 取平台 id:`avibe`(Web/Workbench)、`slack`、`discord`、`telegram`、`lark`、`wechat`。需要更高级的筛选——按 Agent、时间段、消息内容或跨表联查——请使用 `vibe data query`。### `vibe runs`diff --git a/tests/test_cli_task_command.py b/tests/test_cli_task_command.pyindex 50ee12f8c..5345fd8cb 100644--- a/tests/test_cli_task_command.py+++ b/tests/test_cli_task_command.py@@ -3,7 +3,6 @@ from __future__ import annotationsimport ioimport jsonimport os-import shleximport sqlite3import sysfrom contextlib import redirect_stderr@@ -338,7 +337,7 @@ def test_supported_task_platforms_always_includes_avibe() -> None:assert "avibe" in cli._supported_task_platforms()-def test_task_help_describes_session_id_guidance(capsys) -> None:+def test_task_help_examples_use_the_caller_session_default(capsys) -> None:parser = cli.build_parser()with pytest.raises(SystemExit) as exc:@@ -346,29 +345,27 @@ def test_task_help_describes_session_id_guidance(capsys) -> None:assert exc.value.code == 0captured = capsys.readouterr()- assert "Create, inspect, and control scheduled Agent messages for Avibe." in captured.out- assert "vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message" in captured.outassert "{add,update,list,show,pause,resume,run,remove}" in captured.out+ assert "vibe task add --cron '0 * * * *' --message 'Share the hourly summary.'" in captured.out+ assert "--session-id" not in captured.outassert "rm (remove)" not in captured.outassert "\n ls" not in captured.out-def test_task_add_help_includes_examples_and_threadless_guidance(capsys) -> None:+def test_task_add_help_states_task_kinds_and_cron_weekday_names(capsys) -> None:parser = cli.build_parser()with pytest.raises(SystemExit) as exc:parser.parse_args(["task", "add", "--help"])assert exc.value.code == 0- captured = capsys.readouterr()- assert "If this is your first time using this command, read this whole help entry before creating a task." in captured.out- assert "`--session-id` chooses which Agent Session Avibe will continue using when the task runs." in captured.out- assert "tasks continue this conversation by default" in captured.out- assert "--post-to" not in captured.out- assert "--same-scope" in captured.out- assert "--scope-id" in captured.out- assert "--deliver-key" not in captured.out- assert "Write cron weekdays as names (mon, tue, ... sun)." in captured.out+ text = " ".join(capsys.readouterr().out.split())+ assert "A message task stores --message and sends it to the target Session on each run." in text+ assert "A command task (--shell, or a command after '--') runs with no Agent turn." in text+ assert "with --on-failure agent starts one Agent turn" in text+ assert "Only that form takes Session, scope, or Agent flags." in text+ assert "Write cron weekdays as names (mon ... sun): numbers are rejected" in text+ assert "vibe task add --cron '0 9 * * mon-fri' --message" in textdef test_task_list_help_mentions_completed_one_shots_hidden_by_default(capsys) -> None:@@ -386,64 +383,36 @@ def test_task_list_help_mentions_completed_one_shots_hidden_by_default(capsys) -assert "--all" not in captured.out-def test_task_update_help_includes_partial_update_guidance(capsys) -> None:+def test_task_update_help_states_partial_update_and_kind_rules(capsys) -> None:parser = cli.build_parser()with pytest.raises(SystemExit) as exc:parser.parse_args(["task", "update", "--help"])assert exc.value.code == 0- captured = capsys.readouterr()- assert "keeping its task ID" in captured.out- assert "--reset-delivery" in captured.out- assert "Unspecified fields keep their existing values." in captured.out- assert "Write cron weekdays as names (mon, tue, ... sun)." in captured.out+ text = " ".join(capsys.readouterr().out.split())+ assert "Unspecified fields keep their values." in text+ assert "A message task cannot become a command task, or the reverse, and --on-failure cannot change" in text+ assert "Write cron weekdays as names (mon ... sun); numbers are rejected." in text-def test_agent_run_help_includes_fork_session_guidance(capsys) -> None:+def test_agent_run_help_states_session_callback_and_fork_rules(capsys) -> None:parser = cli.build_parser()with pytest.raises(SystemExit) as exc:parser.parse_args(["agent", "run", "--help"])assert exc.value.code == 0- captured = capsys.readouterr()- assert "--fork-session FORK_SESSION" in captured.out- assert "--fork-self" in captured.out- assert "--sync" in captured.out- assert "--send-now" not in captured.out- assert "--create-session" not in captured.out- assert "--async" not in captured.out- assert "--same-scope" in captured.out- assert "--scope-id" in captured.out- assert "--visible" in captured.out- assert "--deliver-key" not in captured.out- assert "Avibe Agent shell examples:" in captured.out- assert "Normal terminal examples:" in captured.out- assert "--fork-self forks this current Session." in captured.out- assert "Forks keep the same backend, scope, and cwd as the source Session." in captured.out- assert "vibe agent run --fork-self --message" in captured.out- assert "vibe agent run --session-id sesk8m4q2p7x --message" in captured.out- assert "vibe session queue list --session-id sesk8m4q2p7x" in captured.out- assert "vibe session queue remove msg_queued123 --session-id sesk8m4q2p7x" in captured.out- assert "vibe session send-now --session-id sesk8m4q2p7x" in captured.out- assert "Agent runs are async by default. From an Avibe Agent shell, they return their final result to this conversation by default." in captured.out- assert "vibe agent run --agent release-reviewer --message 'Review the latest deployment result.'" in captured.out- assert (- "vibe agent run --agent release-reviewer --visible --message 'Review this project in a visible sibling Session.'"- in captured.out- )- assert (- "vibe agent run --agent release-reviewer --no-callback --message 'Review the latest deployment result.'"- not in captured.out- )- assert "vibe agent run --agent release-reviewer --same-scope --no-callback --message" not in captured.out- assert "From a normal terminal, pass --callback-session-id or --no-callback for async runs." in captured.out- assert "Review the latest CI result and print it here." in captured.out- assert "Review the latest CI result and report back." in captured.out- assert "--callback-session-id sescaller456 --message 'Review the latest CI result and report back.'" in captured.out- assert "--no-callback --message 'Review the latest CI result and report back.'" not in captured.out- assert "Do not combine fork flags with --session-id." in captured.out+ text = " ".join(capsys.readouterr().out.split())+ assert "Runs are async: the final result returns to the caller Session." in text+ assert "Elsewhere, pass --callback-session-id, --no-callback, or --sync." in text+ assert "--session-id ID Join this Session's running turn, or start one if idle" in text+ assert "--queue With --session-id: wait for the running turn" in text+ assert "Fork this Session's context, backend, scope, and cwd" in text+ assert "Agent for a new Session (a fork: same backend only)" in text+ assert "--model, --reasoning-effort, --visible, --same-scope, --scope-id, and --close-after apply only to a new or forked Session." in text+ for jargon in ("P1", "P3", "native Turn", "steer"):+ assert jargon not in textdef test_agent_run_visible_sugar_sets_foreground_visibility() -> None:@@ -462,7 +431,7 @@ def test_task_add_parse_error_is_structured_json(capsys) -> None:payload = json.loads(capsys.readouterr().err)assert payload["code"] == "invalid_arguments"assert payload["help_command"] == "vibe task add --help"- assert "--session-id SESSION_ID" in payload["usage"]+ assert "--session-id ID" in payload["usage"]def test_task_remove_parse_error_keeps_structured_guidance(capsys) -> None:@@ -4714,26 +4683,6 @@ def test_task_payload_renders_message_kind_for_message_tasks(tmp_path: Path) ->assert {"command_preview", "last_exit_code"}.isdisjoint(brief)-# --- documented examples -----------------------------------------------------def test_documented_task_command_examples_stay_parseable() -> None:- """Injected help text is a live caller: every example must survive the parser."""-- parser = cli.build_parser()- text = cli._task_add_examples_text() + "\n" + cli._task_update_examples_text()- examples = [- line.strip()- for line in text.splitlines()- if line.strip().startswith(("vibe task add ", "vibe task update "))- ]- command_examples = [line for line in examples if "--shell" in line or "--timeout" in line]- assert len(examples) >= 4- assert len(command_examples) >= 3-- for example in examples:- parser.parse_args(shlex.split(example)[1:])-def test_task_resume_rejects_orphaned_owner_without_execution_target(monkeypatch, tmp_path: Path) -> None:diff --git a/tests/test_cli_watch_command.py b/tests/test_cli_watch_command.pyindex 408b8be0d..92775dbff 100644--- a/tests/test_cli_watch_command.py+++ b/tests/test_cli_watch_command.py@@ -80,7 +80,7 @@ def _add_test_watch()-def test_watch_help_describes_session_id_guidance(capsys) -> None:+def test_watch_help_examples_use_the_caller_session_default(capsys) -> None:parser = cli.build_parser()with pytest.raises(SystemExit) as exc:@@ -88,40 +88,9 @@ def test_watch_help_describes_session_id_guidance(capsys) -> None:assert exc.value.code == 0captured = capsys.readouterr()- assert "managed background watchers" in captured.out- assert "vibe watch add --session-id sesk8m4q2p7x --name 'Wait for export' --message" in captured.outassert "{add,update,list,show,pause,resume,remove}" in captured.out---def test_watch_add_help_mentions_shell_and_lifetime_timeout(capsys) -> None:- parser = cli.build_parser()-- with pytest.raises(SystemExit) as exc:- parser.parse_args(["watch", "add", "--help"])-- assert exc.value.code == 0- captured = capsys.readouterr()- normalized_help = " ".join(captured.out.split())- assert "Pass either --shell '<command>' or a command after '--'." in captured.out- assert "--lifetime-timeout" in captured.out- assert "vibe watch add --session-id sesk8m4q2p7x --message 'The export finished. Inspect it and continue.'" in captured.out- assert "watches follow up in this conversation by default" in captured.out- assert "Use --message or --message-file for follow-up instructions." in captured.out- assert "--prefix" not in captured.out- assert "--session-key" not in captured.out- assert "Terminal failures also send a follow-up and disable the watch." in captured.out- assert "an allowed `--retry-exit-code` keeps waiting" in captured.out- assert "A once Watch stops after its first event" in captured.out- assert "five-second safety delay" in captured.out- assert "automatically pause the Watch" in captured.out- assert "a once Watch ends and a forever Watch re-arms" in captured.out- assert "A once waiter that is still waiting must use a retry exit code" in captured.out- assert "If this is your first time using this command, read this whole help entry before creating a watch." in captured.out- assert "Use 0 for no per-cycle timeout" in normalized_help- assert "--same-scope" in captured.out- assert "--scope-id" in captured.out- assert "--post-to" not in captured.out- assert "--deliver-key" not in captured.out+ assert "vibe watch add --name 'Wait for export' --message" in captured.out+ assert "--session-id" not in captured.outdef test_watch_update_preserves_archived_agent_reference(tmp_path: Path, capsys) -> None:@@ -2116,14 +2085,23 @@ def test_watch_add_refuses_the_reserved_session_with_no_side_effects()-def test_watch_add_help_states_the_no_event_marker_contract() -> None:+def test_watch_add_help_states_the_waiter_contract(capsys) -> None:"""The help is a live caller of the waiter contract, not a description of it.A custom waiter written from this text is what the supervisor then judges, soguidance that named the exit code but not the marker sent people straight intoa watch that reports a failure and disables itself."""- text = cli._watch_add_examples_text()-- assert str(watches.NO_EVENT_EXIT_CODE) in text- assert watches.NO_EVENT_MARKER in text+ with pytest.raises(SystemExit):+ cli.build_parser().parse_args(["watch", "add", "--help"])+ text = capsys.readouterr().out++ assert "0 one new event" in text+ assert f"{watches.DEFAULT_RETRY_EXIT_CODE} still waiting (any --retry-exit-code)" in text+ assert f"{watches.NO_EVENT_EXIT_CODE} plus the stderr line '{watches.NO_EVENT_MARKER}'" in text+ assert f"A bare {watches.NO_EVENT_EXIT_CODE} is a failure" in text+ assert "failure (124 = timed out)" in text+ assert "A once Watch stops at its first event or quiet cycle; --forever re-arms after each." in text+ assert "rapid repeats pause the Watch" in text+ first_example = next(line for line in text.splitlines() if line.strip().startswith("vibe watch add"))+ assert "--session-id" not in first_examplediff --git a/tests/test_prompt_render_export.py b/tests/test_prompt_render_export.pyindex 0af222b7d..780dc5be8 100644--- a/tests/test_prompt_render_export.py+++ b/tests/test_prompt_render_export.py@@ -68,6 +68,15 @@ _FOLLOW_THROUGH_PRINCIPLE = ("across turns as well as within one. When repeatedly blocked, rethink the approach instead of ""retrying it. Stop only to wait on a stated condition or at an explained blocker.")+_PREVIOUS_SESSION_TITLE_STEPS = (+ "without waiting for the user. First inspect:\n`vibe session get`\n\n"+ "If `metadata.title_source` is `user` or `agent`, leave the title unchanged. Otherwise set it once:\n"+ '`vibe session update --title "<short title>"`\n\nDo not mention'+)+_SESSION_TITLE_STEPS = (+ 'without waiting for the user:\n`vibe session update --title "<short title>" --if-untitled`\n\n'+ "It keeps a title the user or an Agent already set. Do not mention"+)_CODEX_SKILL_REUSE_GUIDANCE = ("Choose skills by task relevance, but load a skill only if it has not already been read ""in this conversation; reuse already-loaded instructions across turns, callbacks, "@@ -553,7 +562,9 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatcassert text.count(_FOLLOW_THROUGH_PRINCIPLE) == 1assert text.count(_NEW_SESSION_MODEL_GUIDANCE) == 1assert text.count(_HARNESS_SOURCE_GUIDANCE) == 1+ assert text.count(_SESSION_TITLE_STEPS) == 1text = text.replace(_HARNESS_SOURCE_GUIDANCE, "")+ text = text.replace(_SESSION_TITLE_STEPS, _PREVIOUS_SESSION_TITLE_STEPS)text = text.replace(_NEW_SESSION_MODEL_GUIDANCE, _PREVIOUS_FORK_OVERRIDE_GUIDANCE)text = text.replace(_HISTORY_AS_MEMORY_GUIDANCE, _PREVIOUS_HISTORY_GUIDANCE)text = text.replace(_FOLLOW_THROUGH_PRINCIPLE, _PREVIOUS_FOLLOW_THROUGH_PRINCIPLE)@@ -565,6 +576,7 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatc# verification principle and conversation-history guidance and Follow-through# principle, and the Harness rule that a run's --model applies# only to forks (now: to any new Session a run creates), and without the- # Harness line that says what a `[Harness: ...]` input is.+ # Harness line that says what a `[Harness: ...]` input is, and restoring the+ # two-call Session Title steps that `--if-untitled` replaced.# Every other byte/order stays pinned, including all Claude/OpenCode output.assert digest == "262c7cbabbbb0bfefa4a69511d805d28f76a3559bd511184006242f831b4836e"diff --git a/tests/test_session_cli.py b/tests/test_session_cli.pyindex 2f6415489..592472ad8 100644--- a/tests/test_session_cli.py+++ b/tests/test_session_cli.py@@ -659,6 +659,83 @@ def test_update_empty_title_clears(monkeypatch, tmp_path, capsys):assert payload["session"]["title"] is None+ ("title_source", "updated"),+ [+ (None, True),+ ("backend", True),+ ("derived_first_prompt", True),+ ("user", False),+ ("agent", False),+ ],+)+def test_update_if_untitled_keeps_only_a_deliberate_title(monkeypatch, tmp_path, capsys, title_source, updated):+ """The Session Title prompt's one call: an automatic title counts as untitled."""+ engine = _setup(monkeypatch, tmp_path)+ _seed(engine, "sesaaa", title="Old", title_source=title_source)++ code, payload = _run(+ cli.cmd_session_update,+ ["session", "update", "--session-id", "sesaaa", "--title", "New name", "--if-untitled"],+ capsys,+ )++ assert code == 0+ assert payload["updated"] is updated+ assert payload["session"]["title"] == ("New name" if updated else "Old")+ assert payload["session"]["metadata"].get("title_source") == ("agent" if updated else title_source)+++def test_update_if_untitled_never_overwrites_a_concurrent_user_rename(monkeypatch, tmp_path, capsys):+ """A rename committed while the call waits wins, because the check holds the write lock."""+ import threading+ import time++ engine = _setup(monkeypatch, tmp_path)+ _seed(engine, "sesaaa", title="Auto", title_source="backend")+ args = cli.build_parser().parse_args(+ ["session", "update", "--session-id", "sesaaa", "--title", "Agent name", "--if-untitled"]+ )+ result = {}+ with engine.connect() as web:+ web.exec_driver_sql("BEGIN IMMEDIATE")+ web.execute(+ agent_sessions.update()+ .where(agent_sessions.c.id == "sesaaa")+ .values(title="User name", metadata_json=json.dumps({"title_source": "user"}))+ )+ worker = threading.Thread(target=lambda: result.update(code=cli.cmd_session_update(args)))+ worker.start()+ time.sleep(0.5) # let the CLI reach the lock before the rename commits+ web.commit()+ worker.join(timeout=10)++ assert result["code"] == 0+ assert json.loads(capsys.readouterr().out)["updated"] is False+ with engine.connect() as conn:+ assert conn.execute(+ agent_sessions.select().where(agent_sessions.c.id == "sesaaa")+ ).mappings().one()["title"] == "User name"+++ "extra",+ [[], ["--title", "x", "--hidden"], ["--title", "x", "--scope-id", "none"]],+)+def test_update_if_untitled_applies_only_to_title(monkeypatch, tmp_path, capsys, extra):+ engine = _setup(monkeypatch, tmp_path)+ _seed(engine, "sesaaa", title="Old")++ code, payload = _run(+ cli.cmd_session_update,+ ["session", "update", "--session-id", "sesaaa", "--if-untitled", *extra],+ capsys,+ )++ assert code == 1+ assert payload["code"] == "invalid_arguments"++def test_update_help_teaches_visibility_sugar(capsys):parser = cli.build_parser()@@ -836,13 +913,11 @@ def test_web_title_prompt_defaults_to_current_session():out = _injection_for("sesweb")title_prompt = out[out.index("## Session Title") :]assert "## Session Title" in out- assert "`vibe session get`" in out- assert '`vibe session update --title "<short title>"`' in out- assert "vibe session get sesweb" not in out- assert 'vibe session update sesweb --title "<short title>"' not in out- assert "metadata.title_source" in out- assert "`user` or `agent`" in out- assert "leave the title unchanged" in out+ # One call: the CLI keeps a deliberate title, so no `vibe session get` first.+ assert '`vibe session update --title "<short title>" --if-untitled`' in title_prompt+ assert "vibe session get" not in title_prompt+ assert "sesweb" not in title_prompt+ assert "keeps a title the user or an Agent already set" in outassert "silently set one concise, human-scannable Session title" in outassert "without waiting for the user" in outassert "do not rename it again" in outdiff --git a/tests/test_show_pages.py b/tests/test_show_pages.pyindex 0dd1f957d..5682cb151 100644--- a/tests/test_show_pages.py+++ b/tests/test_show_pages.py@@ -114,8 +114,7 @@ def test_show_without_subcommand_prints_help(capsys):assert "Manage the one visual Show Page attached to an Agent Session." in captured.outassert "usage: vibe show [-h]" in captured.outassert "{list,path,status,update,mark,reply,marks,unmark,event,annotate} ..." in " ".join(captured.out.split())- assert "vibe show list" in captured.out- assert "vibe show path --session-id sesk8m4q2p7x" in captured.out+ assert " vibe show path\n" in captured.outassert "Accept: text/markdown" in captured.outdiff --git a/tests/test_vibe_cli.py b/tests/test_vibe_cli.pyindex ab6e531fd..aff4335ae 100644--- a/tests/test_vibe_cli.py+++ b/tests/test_vibe_cli.py@@ -76,25 +76,26 @@ def _write_alembic_revision(db_path: Path, revision: str) -> None:conn.execute("insert into alembic_version values (?)", (revision,))+def _parser_leaves(parser, path=()):+ import argparse++ yield path, parser+ for action in parser._actions:+ if isinstance(action, argparse._SubParsersAction):+ for name, child in action.choices.items():+ yield from _parser_leaves(child, (*path, name))++def test_cli_text_is_english_whatever_the_ui_language(monkeypatch, tmp_path, capsys):"""Agents read CLI help and errors; they stay English when the Web UI is set to Chinese."""- import argparse-config_path = tmp_path / "config.json"config_path.write_text(json.dumps({"language": "zh"}), encoding="utf-8")monkeypatch.setattr(cli.paths, "get_config_path", lambda: config_path)monkeypatch.setattr(cli.V2Config, "load", lambda *_args, **_kwargs: SimpleNamespace(language="zh"))han = re.compile(r"[\u4e00-\u9fff]")- def leaves(parser, path=()):- yield path, parser- for action in parser._actions:- if isinstance(action, argparse._SubParsersAction):- for name, child in action.choices.items():- yield from leaves(child, (*path, name))-- for path, parser in leaves(cli.build_parser()):+ for path, parser in _parser_leaves(cli.build_parser()):help_text = parser.format_help()assert not han.search(help_text), f"vibe {' '.join(path)} --help is not English"@@ -103,6 +104,24 @@ def test_cli_text_is_english_whatever_the_ui_language(monkeypatch, tmp_path, capassert not han.search(capsys.readouterr().err)+def test_every_help_fits_its_budget_and_its_examples_parse(monkeypatch):+ """Agents read --help before a first call, pay for every byte, and copy its examples."""++ monkeypatch.setenv("COLUMNS", "80") # what a non-TTY Agent shell renders+ for path, parser in _parser_leaves(cli.build_parser()):+ command = " ".join(("vibe", *path))+ size = len(parser.format_help().encode())+ assert size <= 2560, f"{command} --help is {size} bytes; keep it within 2.5 KiB"+ for line in (parser.epilog or "").splitlines():+ example = line.strip()+ if not example.startswith("vibe "):+ continue+ try:+ cli.build_parser().parse_args(shlex.split(example, comments=True)[1:])+ except SystemExit as exc:+ raise AssertionError(f"{command} --help teaches an unparseable example: {example!r}") from exc++def test_top_level_help_lists_only_public_commands(capsys):parser = cli.build_parser()diff --git a/vibe/cli.py b/vibe/cli.pyindex abb7e3096..28d29d660 100644--- a/vibe/cli.py+++ b/vibe/cli.py@@ -61,6 +61,7 @@ from core.vibe_agents import AgentAlwaysEnabledError, AgentArchivedEditError, Agfrom core.watches import (DEFAULT_RETRY_EXIT_CODE,NO_EVENT_EXIT_CODE,+ NO_EVENT_MARKER,WATCH_RECOVERY_ENTRY_TIMEOUT_SECONDS,WATCH_RECONCILE_INTERVAL_SECONDS,JobWatchUpdateRefused,@@ -1159,10 +1160,9 @@ def _task_examples_text() -> str:return dedent("""\Examples:- vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message 'Share the hourly summary.'+ vibe task add --cron '0 * * * *' --message 'Share the hourly summary.'vibe task update 12ab34cd56ef --cron '*/30 * * * *' --name 'Half-hour summary'vibe task run 12ab34cd56ef- vibe task add --create-session --scope-id slack::channel::C123 --cron '*/5 * * * *' --message 'Tell a new joke each time.'vibe task add --create-session --scope-id slack::channel::C123 --at '2026-03-31T09:00:00+08:00' --message-file briefing.md""")@@ -1171,36 +1171,17 @@ def _task_examples_text() -> str:def _task_add_examples_text() -> str:return dedent("""\- Session target:- Use --session-id with the target Agent Session ID, for example sesk8m4q2p7x.- Inside an Avibe Agent shell, tasks continue this conversation by default.-- Guidance:- If this is your first time using this command, read this whole help entry before creating a task.- `--session-id` chooses which Agent Session Avibe will continue using when the task runs.- Use --create-session with --scope-id <scopes.id> to create a reusable Session in a specific existing scope.- Use --create-session with --same-scope only from an Avibe Agent shell, where the caller Session scope is available.- Use --cwd only for Sessions created by this task; existing target Sessions keep their own cwd.- `--message` and `--message-file` provide the stored user message that will be sent each time the task runs.- Use --cron for recurring jobs and --at for one-shot jobs.- Write cron weekdays as names (mon, tue, ... sun). Numeric weekdays are rejected because Avibe's scheduler reads 0 as Monday while crontab(5) reads 0 as Sunday.- --timezone controls how --cron and naive --at timestamps are interpreted.-- Command tasks:- A command task runs a subprocess on schedule with NO Agent turn, so it needs no Session, Agent, or message.- Use --shell for a shell command string, or pass the executable and its args after '--'.- Failure handling is silent-success by default: a successful run stays quiet, and a failed run records a failure notice.- Add --on-failure agent with --message to spend an Agent turn triaging a failed run instead.- --timeout bounds one run; use 0 for no timeout.- --cwd is where the command runs; without it, a Session-bound command follows that Session's directory- and every other command records the directory you ran this from.+ A message task stores --message and sends it to the target Session on each run.+ A command task (--shell, or a command after '--') runs with no Agent turn. A success is+ silent; a failure records a notice, or with --on-failure agent starts one Agent turn+ with the failure and --message. Only that form takes Session, scope, or Agent flags.+ Write cron weekdays as names (mon ... sun): numbers are rejected, because Avibe reads+ 0 as Monday and crontab(5) reads it as Sunday.Examples:- vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message 'Share the hourly summary.'- vibe task add --create-session --scope-id slack::channel::C123 --cron '*/5 * * * *' --message 'Tell a new joke each time.'- vibe task add --create-session --scope-id slack::channel::C123 --cron '0 9 * * *' --message 'Post a visible daily summary in this scope.'- vibe task add --name nightly-sync --cron '0 3 * * *' --shell './scripts/sync.sh'- vibe task add --cron '0 3 * * *' --shell './scripts/sync.sh' --on-failure agent --message 'The nightly sync failed. Diagnose it.'+ vibe task add --cron '0 9 * * mon-fri' --message 'Share the morning summary.'+ vibe task add --at '2026-03-31T09:00:00+08:00' --create-session --scope-id slack::channel::C123 --message-file briefing.md+ vibe task add --cron '0 3 * * *' --shell './scripts/sync.sh' --on-failure agent --message 'The sync failed. Diagnose it.'""")@@ -1208,26 +1189,14 @@ def _task_add_examples_text() -> str:def _task_update_examples_text() -> str:return dedent("""\- You may update any subset of the stored task fields while keeping the same task ID.-- Common updates:- vibe task update 12ab34cd56ef --name 'Morning summary'- vibe task update 12ab34cd56ef --cron '*/30 * * * *'- vibe task update 12ab34cd56ef --message 'Send a shorter summary.'- vibe task update 12ab34cd56ef --session-id sesk8m4q2p7x- vibe task update 12ab34cd56ef --create-session --scope-id slack::channel::C123- vibe task update 12ab34cd56ef --reset-delivery- vibe task update 12ab34cd56ef --shell './scripts/sync.sh --verbose'- vibe task update 12ab34cd56ef --timeout 900-- Guidance:- Unspecified fields keep their existing values.- A command task and a message task are different kinds: remove and recreate the task to move between them, or to change --on-failure.- Use --reset-delivery to return to following the session target directly.- Use --same-scope or --scope-id when this task should create new Sessions in a specific scope.- When changing schedule fields, pass either --cron or --at.- Write cron weekdays as names (mon, tue, ... sun). Numeric weekdays are rejected because Avibe's scheduler reads 0 as Monday while crontab(5) reads 0 as Sunday.- Use --clear-name if you want the task to stop storing a custom name.+ Unspecified fields keep their values. A message task cannot become a command task, or+ the reverse, and --on-failure cannot change: remove the task and add a new one.+ Write cron weekdays as names (mon ... sun); numbers are rejected.++ Examples:+ vibe task update 12ab34cd56ef --cron '0 9 * * mon-fri'+ vibe task update 12ab34cd56ef --name 'Morning summary' --message 'Send a shorter summary.'+ vibe task update 12ab34cd56ef --shell './scripts/sync.sh --verbose' --timeout 900""")@@ -1236,9 +1205,8 @@ def _watch_examples_text() -> str:return dedent("""\Examples:- vibe watch add --session-id sesk8m4q2p7x --name 'Wait for export' --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'+ vibe watch add --name 'Wait for export' --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'vibe watch add --create-session --scope-id slack::channel::C123 --message 'The CI job finished. Inspect the result.' -- python3 scripts/wait_for_ci.py --build 42- vibe watch add --session-id sesk8m4q2p7x --forever --retry-exit-code 75 --retry-delay 60 --message 'The log pattern appeared. Continue from the result below.' --shell 'bash scripts/wait_for_log_pattern.sh'vibe watch listvibe watch show 12ab34cd56efvibe watch pause 12ab34cd56ef@@ -1924,59 +1892,20 @@ def _remote_pair_examples_text() -> str:def _show_examples_text() -> str:- markdown_help = "Public Show Page links automatically return agent-readable Markdown to Agents and command-line clients. For an authorized private read, request the URL with Accept: text/markdown."return dedent("""\- A Show Page is one session-scoped visual page that Avibe serves through the Web UI / Avibe Cloud tunnel.- One Agent Session has exactly one Show Page.-- Agent-readable representation:- __MARKDOWN_HELP__-- Commands:- list List existing Show Pages across sessions.- path Create or resolve the local workspace.- status Inspect local path, visibility, active URL, and share state.- update Switch visibility, set a custom public link, rotate share links, or take the page offline.- mark Add an assistant mark event to the session.- reply Reply to a dispatched page annotation at its original anchor.- marks List active assistant marks.- unmark Resolve active assistant marks by id or target.- event Record a generic annotation-layer event.- annotate Control the page's annotation overlay.-- Visibility:- private Authenticated Web UI URL under /show/<session-id>/.- public Short unauthenticated share URL under /p/<share-id>/.- offline URL access is revoked; local files remain.+ Each Agent Session has one Show Page, served through the Web UI or the Avibe Cloud tunnel.+ Visibility: private is the signed-in /show/<session-id>/ URL; public is an unauthenticated+ /p/<share-id>/ URL; offline revokes URL access and keeps the local files.+ Public Show Page links automatically return agent-readable Markdown to Agents and+ command-line clients. For an authorized private read, send Accept: text/markdown.Examples:- vibe show list- vibe show list --global --visibility public- vibe show path --session-id sesk8m4q2p7x- vibe show status --session-id sesk8m4q2p7x- vibe show update --session-id sesk8m4q2p7x --visibility public- vibe show update --session-id sesk8m4q2p7x --visibility offline- vibe show mark mark-default-summary --session-id sesk8m4q2p7x --message "Review this summary."- vibe show reply show_evt_1a2b3c4d --message "The source changed in W30."- vibe show marks- vibe show unmark mark_1 mark-default-summary- vibe show event --session-id sesk8m4q2p7x --event-json @./show-event.json- vibe show annotate --session-id sesk8m4q2p7x --on --mode screenshot-- More:- vibe show list --help- vibe show path --help- vibe show status --help- vibe show update --help- vibe show mark --help- vibe show reply --help- vibe show marks --help- vibe show unmark --help- vibe show event --help- vibe show annotate --help+ vibe show path+ vibe show update --visibility public+ vibe show annotate --on --mode screenshot"""- ).replace("__MARKDOWN_HELP__", markdown_help)+ )def _show_path_examples_text() -> str:@@ -2080,35 +2009,19 @@ def _print_json(payload: dict) -> None:def _watch_add_examples_text() -> str:return dedent(- """\- Session target:- Use --session-id with the target Agent Session ID, for example sesk8m4q2p7x.- Inside an Avibe Agent shell, watches follow up in this conversation by default.-- Guidance:- If this is your first time using this command, read this whole help entry before creating a watch.- Use a watch when a script should wait in the background and send a follow-up when it detects an event or reaches a terminal failure.- `--session-id` chooses which Agent Session Avibe will continue using for follow-up messages from the watch.- Use --create-session with --scope-id <scopes.id> to create a reusable Session in a specific existing scope.- Use --create-session with --same-scope only from an Avibe Agent shell, where the caller Session scope is available.- Use --message or --message-file for follow-up instructions.- Terminal failures also send a follow-up and disable the watch.- In either mode, an allowed `--retry-exit-code` keeps waiting. A once Watch stops after its first event.- A forever Watch waits for each event's Agent Run to finish before re-arming, then applies a five-second safety delay.- Exit 0 must mean one new reportable event, not a condition that merely remains true. Repeated rapid successes automatically pause the Watch and send the Agent a repair message.- Waiter exit codes: 0 detected an event and sends the follow-up; 124 timed out and is terminal unless explicitly allowed for retry;- 64 PLUS the line 'avibe-watch: no-event' on stderr means the cycle ran and found nothing worth reporting,- so a once Watch ends and a forever Watch re-arms WITHOUT an Agent turn. A once waiter that is still waiting must use a retry exit code.- Any other non-zero is a failure.- The marker is required: 64 alone is also sysexits EX_USAGE, so a bare 64 stays a failure and stops the watch.- Use it in waiters whose normal outcome is uninteresting, such as green CI.- Pass either --shell '<command>' or a command after '--'.- --timeout applies to each cycle. --lifetime-timeout applies to the whole Watch lifetime across retries and re-arms.+ f"""\+ Waiter exit codes:+ 0 one new event: start the follow-up Run+ {DEFAULT_RETRY_EXIT_CODE} still waiting (any --retry-exit-code): rerun after --retry-delay+ {NO_EVENT_EXIT_CODE} plus the stderr line '{NO_EVENT_MARKER}': quiet cycle, no Agent turn+ other failure (124 = timed out): a follow-up Run, then the Watch stops+ A once Watch stops at its first event or quiet cycle; --forever re-arms after each.+ Exit 0 only for a new event: rapid repeats pause the Watch. A bare {NO_EVENT_EXIT_CODE} is a failure.Examples:- vibe watch add --session-id sesk8m4q2p7x --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'- vibe watch add --create-session --scope-id slack::channel::C123 --message 'The export finished.' -- bash -lc 'sleep 120; echo done'- vibe watch add --session-id sesk8m4q2p7x --forever --timeout 600 --lifetime-timeout 86400 --retry-exit-code 75 --retry-delay 30 --message 'PR #153 changed. Inspect it and continue.' -- uv run --no-project scripts/wait_pr.py --repo avibe-bot/avibe --pr 153+ vibe watch add --name export --message 'The export finished. Check it.' -- python3 wait_export.py+ vibe watch add --forever --timeout 0 --message 'The deploy changed.' --shell './wait_deploy.sh'+ vibe watch add --create-session --scope-id slack::channel::C123 --message 'Build done.' -- make build""")@@ -2116,50 +2029,15 @@ def _watch_add_examples_text() -> str:def _agent_run_examples_text() -> str:return dedent("""\- Session target:- Use --session-id to continue an existing Agent Session.- The default is P1: steer an active native Turn, start when idle, or fall back to the durable P3 queue.- Add --queue to persist this Run as P3 behind the active Turn.- To promote the exact existing P3 queue head without a new message, use: vibe session send-now --session-id <session-id>- Inspect queued work with: vibe session queue list --session-id <session-id>- Remove one exact queued row with: vibe session queue remove <message-id> --session-id <session-id>- Omit --session-id/--fork-self/--fork-session to create a background Session for --agent.- Inside an Agent shell it inherits the caller scope and invocation cwd; outside one it is standalone with its own Show workspace.- Use --same-scope to explicitly place a new Session in the caller/source Session's scope.- Use --scope-id <scopes.id> to place a new Session in a specific existing scope.- New and forked delegated Sessions are background by default; pass --visible to make them user-facing and enable outward delivery.- --cwd only applies to new Sessions; existing Sessions keep their own cwd.-- Callback:- Agent runs are async by default. From an Avibe Agent shell, they return their final result to this conversation by default.- From a normal terminal, pass --callback-session-id or --no-callback for async runs.- Pass --no-callback only when you intentionally want no automatic follow-up.- Pass --callback-session-id only when the final result should return somewhere else.- Pass --sync when the CLI should wait for the run result in the terminal.-- Forking:- --fork-self forks this current Session.- --fork-session <session-id> creates a new Avibe Agent Session and asks the native backend to fork the source native session on the first turn.- Forks keep the same backend, scope, and cwd as the source Session. Passing --agent is allowed only when that Agent uses the same backend.- --agent, --model, and --reasoning-effort may override the forked Session's Agent/model/effort.- Do not combine fork flags with --session-id.-- Avibe Agent shell examples:- vibe agent run --agent release-reviewer --message 'Review the latest deployment result.'- vibe agent run --agent release-reviewer --visible --message 'Review this project in a visible sibling Session.'- vibe agent run --session-id sesk8m4q2p7x --message 'Apply this correction in the current turn.'- vibe session queue list --session-id sesk8m4q2p7x- vibe session queue remove msg_queued123 --session-id sesk8m4q2p7x- vibe session send-now --session-id sesk8m4q2p7x-- Normal terminal examples:- vibe agent run --sync --agent release-reviewer --message 'Review the latest CI result and print it here.'- vibe agent run --agent release-reviewer --callback-session-id sescaller456 --message 'Review the latest CI result and report back.'- vibe agent run --agent release-reviewer --no-callback --message 'Run a background experiment; I will inspect the run later.'-- Fork examples:- vibe agent run --fork-self --message 'Explore this alternate fix from the current context.'- vibe agent run --fork-session sesk8m4q2p7x --agent reviewer --model gpt-5.4 --reasoning-effort high --message 'Review the forked context.'+ Inside an Agent shell a new Session takes the caller's scope and current directory.+ Elsewhere, pass --callback-session-id, --no-callback, or --sync.+ --model, --reasoning-effort, --visible, --same-scope, --scope-id, and --close-after+ apply only to a new or forked Session.++ Examples:+ vibe agent run --agent reviewer --message 'Review the latest deployment result.'+ vibe agent run --session-id sesk8m4q2p7x --queue --message 'After this turn, also update the docs.'+ vibe agent run --fork-self --message 'Explore the alternate fix from this context.'""")@@ -7859,8 +7737,22 @@ def cmd_session_queue_remove(args):def cmd_session_update(args):from core.services import sessions as sessions_service+ from storage.agent_session_rows import reserve_write_lock+ from storage.workbench_sessions_service import DELIBERATE_TITLE_SOURCEStry:+ if_untitled = bool(getattr(args, "if_untitled", False))+ if if_untitled and (+ getattr(args, "title", None) is None+ or getattr(args, "visibility", None) is not None+ or getattr(args, "scope_id", None) is not None+ ):+ raise TaskCliError(+ "--if-untitled applies only to --title",+ code="invalid_arguments",+ hint="Pass --title with --if-untitled, and change visibility or scope in a separate call.",+ help_command="vibe session update --help",+ )updates = {}if getattr(args, "title", None) is not None:updates["title"] = args.title@@ -7891,10 +7783,19 @@ def cmd_session_update(args):)engine = _open_session_engine()with engine.begin() as conn:+ # Hold the write lock from before the read, so a rename committed by the+ # Web UI cannot land between the --if-untitled check and this write.+ reserve_write_lock(conn)# Validate first so an archived/missing id is a clean not-found rather# than silently writing a title onto a soft-deleted row.previous_session = sessions_service.get_active_session(conn, session_id)- payload = sessions_service.update_session(conn, session_id, **updates)+ title_source = (previous_session.get("metadata") or {}).get("title_source")+ updated = not (if_untitled and title_source in DELIBERATE_TITLE_SOURCES)+ payload = (+ sessions_service.update_session(conn, session_id, **updates)+ if updated+ else previous_session+ )except LookupError:_print_task_error(TaskCliError(@@ -7910,14 +7811,15 @@ def cmd_session_update(args):return 1# The DB write is committed above; ping a running UI so the rename shows live# (best-effort — never affects this command's result).- _post_session_activity_to_live_ui(- session_id,- previous_scope_id=previous_session.get("scope_id"),- previous_visibility=previous_session.get("visibility"),- )+ if updated:+ _post_session_activity_to_live_ui(+ session_id,+ previous_scope_id=previous_session.get("scope_id"),+ previous_visibility=previous_session.get("visibility"),+ )_print_cli_payload("agent_session",- updated=True,+ updated=updated,session=_session_row(payload, brief=False),)return 0@@ -17295,59 +17197,49 @@ def build_parser():agent_run_parser = agent_subparsers.add_parser("run",help="Run an Avibe Agent",- description="Run an Avibe Agent turn. Runs are async by default; use --sync to wait for the result.",+ description=(+ "Run an Agent turn in a new background Session (--agent), an existing Session "+ "(--session-id), or a fork. Runs are async: the final result returns to the caller Session."+ ),epilog=_agent_run_examples_text(),formatter_class=argparse.RawDescriptionHelpFormatter,error_help_command="vibe agent run --help",)- agent_run_parser.add_argument("--agent", help="Avibe Agent name")- agent_run_parser.add_argument("--session-id", help="Existing Agent Session ID to continue")+ agent_run_parser.add_argument("--agent", metavar="NAME", help="Agent for a new Session (a fork: same backend only)")agent_run_parser.add_argument(- "--queue",- action="store_true",- help="Queue this Run behind the active Turn instead of steering it",+ "--session-id", metavar="ID", help="Join this Session's running turn, or start one if idle")- agent_run_parser.add_argument("--fork-session", help="Existing Agent Session ID to fork into a new Session")- agent_run_parser.add_argument("--fork-self", action="store_true", help="Fork this current Agent Session")- agent_run_parser.add_argument("--same-scope", action="store_true", help="Place a new or forked Session in the caller/source Session scope")- agent_run_parser.add_argument("--scope-id", help="Existing scopes.id that should own the new or forked Session")+ agent_run_parser.add_argument("--queue", action="store_true", help="With --session-id: wait for the running turn")+ agent_run_parser.add_argument("--fork-session", metavar="ID", help="Fork this Session's context, backend, scope, and cwd")+ agent_run_parser.add_argument("--fork-self", action="store_true", help="Fork the caller Session")+ agent_run_parser.add_argument("--same-scope", action="store_true", help="Place the new Session in the caller's scope")+ agent_run_parser.add_argument("--scope-id", metavar="ID", help="Place the new Session in this scopes.id")agent_run_parser.add_argument("--visible",dest="visibility",action="store_const",const="foreground",- help="Make the new or forked Session user-facing from the start (default: background)",- )- agent_run_parser.add_argument(- "--model", help="Model for the new Session this run creates (a blank new Session or a fork); kept on that Session for its later turns. Not valid with --session-id. See `vibe agent models <agent>`."- )- agent_run_parser.add_argument(- "--reasoning-effort", help="Reasoning effort for the new Session this run creates; kept on that Session. Not valid with --session-id."+ help="Make the new Session user-facing",)- agent_run_parser.add_argument(- "--cwd",- help=(- "Working directory for the NEW session. Caller-delegated sessions default to the invocation "- "directory; explicit scoped sessions use the scope workdir; standalone sessions use their Show workspace. Invalid with --session-id "- "(an existing session keeps its own working directory)."- ),- )- agent_run_parser.add_argument("--callback-session-id", help="Caller Session ID to receive the completed async run result")+ agent_run_parser.add_argument("--model", help="Model the new Session keeps; see 'vibe agent models <agent>'")+ agent_run_parser.add_argument("--reasoning-effort", metavar="EFFORT", help="Reasoning effort the new Session keeps")+ agent_run_parser.add_argument("--cwd", metavar="DIR", help="Working directory for a new, unforked Session")+ agent_run_parser.add_argument("--callback-session-id", metavar="ID", help="Send the result to this Session instead")agent_run_parser.add_argument("--no-callback",action="store_true",- help="For async runs, intentionally skip automatic callback delivery and inspect the run later.",+ help="Send the result nowhere; read it with 'vibe runs show'",)agent_run_parser.add_argument("--close-after",action="store_true",- help="Close the newly-created Agent runtime after the run settles while keeping its Session and transcript.",+ help="Release the new Session's runtime when the run ends",)- agent_run_parser.add_argument("--sync", dest="sync_run", action="store_true", help="Wait for the run result before exiting")- agent_run_parser.add_argument("--wait-timeout", type=float, help="Maximum seconds the CLI waits for a synchronous run result")+ agent_run_parser.add_argument("--sync", dest="sync_run", action="store_true", help="Wait and print the finished run")+ agent_run_parser.add_argument("--wait-timeout", metavar="SEC", type=float, help="With --sync: maximum seconds to wait")agent_message_group = agent_run_parser.add_mutually_exclusive_group(required=True)- agent_message_group.add_argument("--message")- agent_message_group.add_argument("--message-file")+ agent_message_group.add_argument("--message", metavar="TEXT", help="Message for the Agent")+ agent_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")_add_json_noop(agent_run_parser)runs_parser = subparsers.add_parser(@@ -17524,6 +17416,11 @@ def build_parser():session_update_parser.add_argument("--title", help="New title. Pass an empty string to clear it (reverts to id-based display).")+ session_update_parser.add_argument(+ "--if-untitled",+ action="store_true",+ help="Set --title only if no user or Agent has titled the Session; else keep it (updated: false).",+ )session_visibility_group = session_update_parser.add_mutually_exclusive_group()session_visibility_group.add_argument("--visible",@@ -18151,120 +18048,88 @@ def build_parser():task_add_parser = task_subparsers.add_parser("add",help="Create a scheduled task",- description="Create a recurring or one-shot scheduled Agent message.",+ description="Schedule an Agent message (message task) or a command with no Agent turn (command task).",epilog=_task_add_examples_text(),formatter_class=argparse.RawDescriptionHelpFormatter,error_help_command="vibe task add --help",- error_hint="Use --session-id together with exactly one schedule flag and one message input flag. Use --same-scope or --scope-id when the task creates a new Session.",- )- task_add_parser.add_argument(- "--name",- help="Optional human-friendly task name",- )- task_add_parser.add_argument(- "--session-id",- help="Agent Session ID to continue when the task runs.",- )- task_add_parser.add_argument("--create-session", action="store_true", help="Create one reusable Avibe Session ID for this task")- task_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this task runs")- task_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller Session scope")- task_add_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")- task_add_parser.add_argument("--agent", help="Avibe Agent name to use when the task runs")- task_add_parser.add_argument(- "--cwd",- help=(- "Working directory for Sessions created by this task, and for a command task, "- "the directory its command runs in. Defaults to the caller's current directory."- ),- )+ error_hint="Pass --cron or --at, plus --message, --shell, or a command after '--'.",+ )+ task_add_parser.add_argument("--name", help="Display name")+ task_add_parser.add_argument("--session-id", metavar="ID", help="Run in this Session instead of the caller")+ task_add_parser.add_argument("--create-session", action="store_true", help="Run in one new reusable Session")+ task_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each run")+ task_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller's scope")+ task_add_parser.add_argument("--scope-id", metavar="ID", help="Place a created Session in this scopes.id")+ task_add_parser.add_argument("--agent", metavar="NAME", help="Agent that runs the message")+ task_add_parser.add_argument("--cwd", metavar="DIR", help="Created Session's directory; also where a command runs")schedule_group = task_add_parser.add_mutually_exclusive_group(required=True)- schedule_group.add_argument(- "--cron", help="Recurring schedule in 5-field crontab format; write weekdays as names (mon ... sun)"- )- schedule_group.add_argument("--at", help="One-shot timestamp in ISO 8601 format")+ schedule_group.add_argument("--cron", metavar="EXPR", help="Recurring 5-field cron schedule")+ schedule_group.add_argument("--at", metavar="TIME", help="One-shot ISO 8601 time")# Not ``required=True`` any more: a command task carries no message at all, so the# "message or command" choice is enforced in ``cmd_task_add`` where both inputs are# visible (``missing_task_action``).prompt_group = task_add_parser.add_mutually_exclusive_group()- prompt_group.add_argument("--message", help="Stored user message to send each time the task runs")- prompt_group.add_argument("--message-file", help="Read stored user message from a UTF-8 text file")- task_add_parser.add_argument("--timezone", help="IANA timezone name used for --cron and naive --at values")- task_add_parser.add_argument(- "--shell",- help="Shell command to run on schedule. Use this or pass a command after '--'.",- )+ prompt_group.add_argument("--message", metavar="TEXT", help="Message sent on each run")+ prompt_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")+ task_add_parser.add_argument("--timezone", metavar="TZ", help="IANA timezone for --cron and a naive --at")+ task_add_parser.add_argument("--shell", metavar="CMD", help="Command task: one shell command string")task_add_parser.add_argument("--on-failure",choices=["none", "agent"],default=None,- help="What a failed command run does: 'none' records the failure, 'agent' starts an Agent turn to triage it. Default: none",+ help="Command task failure: record a notice, or start an Agent turn",)task_add_parser.add_argument("--timeout",+ metavar="SEC",type=float,- help="Per-run timeout in seconds for command tasks. Use 0 for no timeout. Default: 21600.",+ help="Command task per-run timeout; 0 = none. Default: 21600",)task_add_parser.add_argument("command_argv",nargs=argparse.REMAINDER,- help="-- followed by the command to run on schedule",+ help="Or the command task's command after '--'",)_add_json_noop(task_add_parser)task_update_parser = task_subparsers.add_parser("update",help="Update a scheduled task",- description="Update one stored scheduled task while keeping its task ID.",+ description="Update one scheduled task in place; unspecified fields keep their values.",epilog=_task_update_examples_text(),formatter_class=argparse.RawDescriptionHelpFormatter,error_help_command="vibe task update --help",error_hint="Pass the task ID plus at least one field to change. Unspecified fields keep their existing values.",)task_update_parser.add_argument("task_id", help="Task ID from 'vibe task list'")- task_update_parser.add_argument("--name", help="New human-friendly task name")- task_update_parser.add_argument(- "--clear-name",- action="store_true",- help="Remove the stored custom task name",- )- task_update_parser.add_argument("--session-id", help="Replace the stored Agent Session ID")- task_update_parser.add_argument("--create-session", action="store_true", help="Replace the task with one reusable newly-created Avibe Session ID")- task_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this task runs")- task_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller Session scope")- task_update_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")- task_update_parser.add_argument("--agent", help="Replace the Avibe Agent used by this task")- task_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the stored Avibe Agent override")- task_update_parser.add_argument(- "--cwd",- help="Set working directory for Sessions created by this task, or for a command task, where its command runs",- )+ task_update_parser.add_argument("--name", help="Set the display name")+ task_update_parser.add_argument("--clear-name", action="store_true", help="Clear the display name")+ task_update_parser.add_argument("--session-id", metavar="ID", help="Run in this Session")+ task_update_parser.add_argument("--create-session", action="store_true", help="Run in one new reusable Session")+ task_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each run")+ task_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller's scope")+ task_update_parser.add_argument("--scope-id", metavar="ID", help="Place created Sessions in this scopes.id")+ task_update_parser.add_argument("--agent", metavar="NAME", help="Set the Agent")+ task_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the Agent override")+ task_update_parser.add_argument("--cwd", metavar="DIR", help="Directory for created Sessions, or the command's")task_update_parser.add_argument("--reset-delivery",action="store_true",- help="Clear any stored delivery override so delivery follows the session target directly",- )- task_update_parser.add_argument(- "--cron", help="Replace the schedule with a recurring 5-field crontab; write weekdays as names (mon ... sun)"- )- task_update_parser.add_argument("--at", help="Replace the schedule with a one-shot ISO 8601 timestamp")- task_update_parser.add_argument("--message", help="Replace the stored user message text")- task_update_parser.add_argument("--message-file", help="Replace the stored user message from a UTF-8 text file")- task_update_parser.add_argument("--timezone", help="Replace the stored IANA timezone name")- task_update_parser.add_argument(- "--shell",- help="Replace the shell command a command task runs. Use this or pass a command after '--'.",- )+ help="Clear the delivery override; deliver to the Session",+ )+ task_update_parser.add_argument("--cron", metavar="EXPR", help="Switch to this recurring cron schedule")+ task_update_parser.add_argument("--at", metavar="TIME", help="Switch to this one-shot ISO 8601 time")+ task_update_parser.add_argument("--message", metavar="TEXT", help="Replace the message")+ task_update_parser.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")+ task_update_parser.add_argument("--timezone", metavar="TZ", help="Set the IANA timezone")+ task_update_parser.add_argument("--shell", metavar="CMD", help="Replace the command; or pass one after '--'")task_update_parser.add_argument("--on-failure",choices=["none", "agent"],default=None,help=argparse.SUPPRESS,)- task_update_parser.add_argument(- "--timeout",- type=float,- help="Replace the per-run timeout in seconds for a command task. Use 0 for no timeout.",- )+ task_update_parser.add_argument("--timeout", metavar="SEC", type=float, help="Command per-run timeout; 0 = none")# No positional landing slot here: the trailing ``-- <command ...>`` tail is lifted# out of argv before argparse runs, exactly as for 'vibe watch update'.task_update_parser.set_defaults(command_argv=None)@@ -18371,119 +18236,115 @@ def build_parser():watch_add_parser = watch_subparsers.add_parser("add",help="Create a managed background watch",- description="Create a managed background watch that runs a waiter command and sends a follow-up on success or terminal failure.",+ description=(+ "Run a waiter in the background; on an event or a failure, start a follow-up Agent Run "+ "in the caller Session."+ ),epilog=_watch_add_examples_text(),formatter_class=argparse.RawDescriptionHelpFormatter,error_help_command="vibe watch add --help",- error_hint="Use --session-id and either --shell or a command after '--'. Retry exit codes keep either mode waiting; add --forever only when distinct successful events should re-arm the Watch.",- )- watch_add_parser.add_argument("--name", help="Optional human-friendly watch name")- watch_add_parser.add_argument(- "--session-id",- help="Agent Session ID to continue for follow-up messages from this watch.",- )- watch_add_parser.add_argument("--create-session", action="store_true", help="Create one reusable Avibe Session ID for this watch")- watch_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this watch triggers")- watch_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller Session scope")- watch_add_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")- watch_add_parser.add_argument("--agent", help="Avibe Agent name to use for follow-up messages")+ error_hint="Pass the waiter as --shell '<command>' or as a command after '--'.",+ )+ watch_add_parser.add_argument("--name", help="Display name")+ watch_add_parser.add_argument("--session-id", metavar="ID", help="Follow up in this Session instead of the caller")+ watch_add_parser.add_argument("--create-session", action="store_true", help="Follow up in one new reusable Session")+ watch_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each follow-up")+ watch_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller's scope")+ watch_add_parser.add_argument("--scope-id", metavar="ID", help="Place a created Session in this scopes.id")+ watch_add_parser.add_argument("--agent", metavar="NAME", help="Agent for the follow-up Run")watch_message_group = watch_add_parser.add_mutually_exclusive_group()- watch_message_group.add_argument("--message", help="Follow-up user message template sent with waiter output")- watch_message_group.add_argument("--message-file", help="Read follow-up user message from a UTF-8 text file")- watch_add_parser.add_argument("--cwd", help="Working directory for the waiter process")+ watch_message_group.add_argument("--message", metavar="TEXT", help="Follow-up instructions; waiter stdout is appended")+ watch_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")+ watch_add_parser.add_argument("--cwd", metavar="DIR", help="Waiter working directory")watch_add_parser.add_argument("--timeout",+ metavar="SEC",type=float,default=21600,- help="Per-cycle timeout in seconds. Use 0 for no per-cycle timeout. Default: 21600",- )- watch_add_parser.add_argument(- "--forever",- action="store_true",- help="Monitor distinct events continuously. After each event's Agent Run settles, the Watch re-arms; terminal failures still stop it unless their exit code is retryable.",+ help="Per-cycle timeout; 0 = none. Default: 21600",)+ watch_add_parser.add_argument("--forever", action="store_true", help="Re-arm after each event instead of stopping")watch_add_parser.add_argument("--lifetime-timeout",+ metavar="SEC",type=float,default=0,- help="Overall Watch lifetime timeout in seconds across retries and re-arms. Use 0 for no lifetime limit.",+ help="Total lifetime; 0 = none (default)",)watch_add_parser.add_argument("--retry-exit-code",+ metavar="N",dest="retry_exit_code",action="append",type=int,default=None,- help=f"Cycle exit code that should keep waiting. Repeat to add more. Default: {DEFAULT_RETRY_EXIT_CODE}",+ help=f"Still-waiting exit code; repeatable. Default: {DEFAULT_RETRY_EXIT_CODE}",)watch_add_parser.add_argument("--retry-delay",+ metavar="SEC",type=float,default=30,- help="Delay in seconds before retrying an allowed cycle result. Default: 30",- )- watch_add_parser.add_argument(- "--shell",- help="Shell command to run as the waiter. Use this or pass a command after '--'.",+ help="Seconds before a still-waiting rerun. Default: 30",)+ watch_add_parser.add_argument("--shell", metavar="CMD", help="Waiter as one shell command string")watch_add_parser.add_argument("waiter_command",nargs=argparse.REMAINDER,- help="Waiter command to run after '--'. Example: vibe watch add ... -- python3 script.py --flag value",+ help="Or the waiter command after '--'",)_add_json_noop(watch_add_parser)watch_update_parser = watch_subparsers.add_parser("update",help="Update one background watch",- description="Update stored watch metadata, target, delivery, command, or runtime options.",- epilog="Find watch IDs with: vibe watch list",+ description="Update a watch's target, message, waiter, or timing. Unspecified fields keep their values.",+ epilog="Exit codes and modes: vibe watch add --help",formatter_class=argparse.RawDescriptionHelpFormatter,error_help_command="vibe watch update --help",error_hint="Pass at least one field to update, such as --name, --shell, --timeout, --session-id, or --scope-id.",)watch_update_parser.add_argument("watch_id", help="Watch ID from 'vibe watch list'")- watch_update_parser.add_argument("--name", help="Set a human-friendly watch name")- watch_update_parser.add_argument("--clear-name", action="store_true", help="Clear the stored watch name")- watch_update_parser.add_argument(- "--session-id",- help="Agent Session ID to continue for follow-up messages from this watch.",- )- watch_update_parser.add_argument("--create-session", action="store_true", help="Replace the watch with one reusable newly-created Avibe Session ID")- watch_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this watch triggers")- watch_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller Session scope")- watch_update_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")- watch_update_parser.add_argument("--agent", help="Replace the Avibe Agent used for follow-up messages")- watch_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the stored Avibe Agent override")+ watch_update_parser.add_argument("--name", help="Set the display name")+ watch_update_parser.add_argument("--clear-name", action="store_true", help="Clear the display name")+ watch_update_parser.add_argument("--session-id", metavar="ID", help="Follow up in this Session")+ watch_update_parser.add_argument("--create-session", action="store_true", help="Follow up in one new reusable Session")+ watch_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each follow-up")+ watch_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller's scope")+ watch_update_parser.add_argument("--scope-id", metavar="ID", help="Place created Sessions in this scopes.id")+ watch_update_parser.add_argument("--agent", metavar="NAME", help="Set the follow-up Agent")+ watch_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the Agent override")watch_update_parser.add_argument("--reset-delivery",action="store_true",- help="Clear any stored delivery override and deliver back to the continued session target.",+ help="Clear the delivery override; deliver to the Session",)watch_update_message_group = watch_update_parser.add_mutually_exclusive_group()- watch_update_message_group.add_argument("--message", help="Replace the follow-up user message template")- watch_update_message_group.add_argument("--message-file", help="Read replacement follow-up user message from a UTF-8 text file")- watch_update_parser.add_argument("--cwd", help="Set working directory for the waiter process")- watch_update_parser.add_argument("--clear-cwd", action="store_true", help="Clear the stored waiter working directory")- watch_update_parser.add_argument("--timeout", type=float, help="Set per-cycle timeout in seconds")+ watch_update_message_group.add_argument("--message", metavar="TEXT", help="Replace the follow-up instructions")+ watch_update_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")+ watch_update_parser.add_argument("--cwd", metavar="DIR", help="Set the waiter working directory")+ watch_update_parser.add_argument("--clear-cwd", action="store_true", help="Clear the waiter working directory")+ watch_update_parser.add_argument("--timeout", metavar="SEC", type=float, help="Per-cycle timeout; 0 = none")watch_update_mode_group = watch_update_parser.add_mutually_exclusive_group()- watch_update_mode_group.add_argument("--forever", action="store_true", help="Switch this watch to forever mode")- watch_update_mode_group.add_argument("--once", action="store_true", help="Switch this watch to one-shot mode")+ watch_update_mode_group.add_argument("--forever", action="store_true", help="Re-arm after each event")+ watch_update_mode_group.add_argument("--once", action="store_true", help="Stop after the first event")watch_update_parser.add_argument("--lifetime-timeout",+ metavar="SEC",type=float,- help="Set the overall Watch lifetime timeout across retries and re-arms. Use 0 for no lifetime limit.",+ help="Total lifetime; 0 = none",)watch_update_parser.add_argument("--retry-exit-code",+ metavar="N",dest="retry_exit_code",action="append",type=int,default=None,- help="Replace exit codes that keep this Watch waiting. Repeat to add more.",+ help="Replace the still-waiting exit codes; repeatable",)- watch_update_parser.add_argument("--retry-delay", type=float, help="Set retry delay in seconds")- watch_update_parser.add_argument("--shell", help="Replace waiter with a shell command")+ watch_update_parser.add_argument("--retry-delay", metavar="SEC", type=float, help="Seconds before a still-waiting rerun")+ watch_update_parser.add_argument("--shell", metavar="CMD", help="Replace the waiter; or pass a command after '--'")watch_update_parser.set_defaults(waiter_command=None)_add_json_noop(watch_update_parser)