dev: detach workspace process actions

.yoi/tickets/00001KXT5ZDRE/item.md

@@ -0,0 +1,31 @@
+---
+title: 'Run dev workspace process actions detached by default'
+state: 'closed'
+created_at: '2026-07-18T08:37:37Z'
+updated_at: '2026-07-18T08:40:59Z'
+assignee: null
+queued_by: 'yoi ticket'
+queued_at: '2026-07-18T08:38:38Z'
+---
+
+## 背景
+
+`scripts/dev-workspace.sh` は backend/runtime/frontend の stop/start を扱うため、API worker が依存している process を foreground tool call 中に停止すると tool result 永続化前にセッションを壊す可能性がある。
+
+呼び出し元が `start` / `stop` / `restart` を実行した時点では即座に戻り、実際の mutating action は detached scheduled job として後で走るようにする。
+
+## 要件
+
+- `start` / `stop` / `restart` は既定で detached background job として schedule する。
+- 既定 delay は 60 秒とし、呼び出し元が tool result を返す時間を確保する。
+- scheduled job の pid と log path を呼び出し元に表示する。
+- `status` / `help` は同期実行のままにする。
+- デバッグ用に foreground 実行へ戻せる環境変数を用意する。
+- 実装中に mutating action は実行しない。
+
+## 受け入れ条件
+
+- `bash -n scripts/dev-workspace.sh` が通る。
+- `scripts/dev-workspace.sh --help` に detached 既定挙動と override が表示される。
+- `scripts/dev-workspace.sh status` は引き続き mutation なしで動く。
+- `start` / `stop` / `restart` の実処理分岐は内部 foreground mode 経由に限定され、通常呼び出しでは detached schedule だけを行う。

.yoi/tickets/00001KXT5ZDRE/resolution.md

@@ -0,0 +1 @@
+`scripts/dev-workspace.sh` now schedules `start`, `stop`, and `restart` as detached background jobs by default, returning schedule/log details immediately. `status` and `help` remain synchronous, and `YOI_DEV_WORKSPACE_FOREGROUND=1` preserves an explicit foreground/debug path.

.yoi/tickets/00001KXT5ZDRE/thread.md

@@ -0,0 +1,92 @@
+<!-- event: create author: "yoi ticket" at: 2026-07-18T08:37:37Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---
+
+<!-- event: intake_summary author: hare at: 2026-07-18T08:38:38Z -->
+
+## Intake summary
+
+Marked ready by `yoi ticket state`.
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T08:38:38Z from: planning to: ready reason: cli_state field: state -->
+
+## State changed
+
+Marked ready by `yoi ticket state`.
+
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T08:38:38Z from: ready to: queued reason: queued field: state -->
+
+## State changed
+
+Ticket を `yoi ticket` が queued にしました。
+
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T08:38:38Z from: queued to: inprogress reason: cli_state field: state -->
+
+## State changed
+
+State changed to `inprogress`.
+
+
+---
+
+<!-- event: implementation_report author: hare at: 2026-07-18T08:40:59Z -->
+
+## Implementation report
+
+`scripts/dev-workspace.sh` の mutating actions を既定で detached scheduled job として実行するように変更した。
+
+変更点:
+- `start` / `stop` / `restart` は通常呼び出しでは実処理をせず、detached job を schedule して即時 return する。
+- 既定 delay は `YOI_DEV_ACTION_DELAY_SECONDS=60`。
+- 呼び出し元には `scheduled_action` / `scheduled_pid` / `scheduled_after_seconds` / `scheduled_log` を表示する。
+- scheduled job は `YOI_DEV_WORKSPACE_FOREGROUND=1` を付けて同じ script を再入実行し、そこで実際の start/stop/restart を行う。
+- `status` / `help` は同期実行のまま。
+- デバッグ用に `YOI_DEV_WORKSPACE_FOREGROUND=1` で foreground 実行できるようにした。
+- help に detached 既定挙動と環境変数 override を追記した。
+
+検証:
+- `bash -n scripts/dev-workspace.sh`
+- `scripts/dev-workspace.sh --help >/dev/null`
+- `scripts/dev-workspace.sh status >/dev/null`
+- `git diff --check`
+
+実行しなかったこと:
+- `scripts/dev-workspace.sh start`
+- `scripts/dev-workspace.sh stop`
+- `scripts/dev-workspace.sh restart`
+
+理由:
+- mutating action は schedule 後に backend/runtime/frontend を止めるため、この作業中には実行しない。
+
+
+---
+
+<!-- event: state_changed author: hare at: 2026-07-18T08:40:59Z from: inprogress to: closed reason: closed field: state -->
+
+## State changed
+
+Ticket を closed にしました。
+
+
+---
+
+<!-- event: close author: hare at: 2026-07-18T08:40:59Z status: closed -->
+
+## 完了
+
+`scripts/dev-workspace.sh` now schedules `start`, `stop`, and `restart` as detached background jobs by default, returning schedule/log details immediately. `status` and `help` remain synchronous, and `YOI_DEV_WORKSPACE_FOREGROUND=1` preserves an explicit foreground/debug path.
+
+
+---

scripts/dev-workspace.sh

@@ -12,6 +12,8 @@ FRONTEND_HOST="${YOI_DEV_FRONTEND_HOST:-0.0.0.0}"
 FRONTEND_PORT="${YOI_DEV_FRONTEND_PORT:-5173}"
 
 RUNTIME_ENABLED="${YOI_DEV_RUNTIME_ENABLED:-1}"
+ACTION_DELAY_SECONDS="${YOI_DEV_ACTION_DELAY_SECONDS:-60}"
+FOREGROUND_MODE="${YOI_DEV_WORKSPACE_FOREGROUND:-0}"
 
 usage() {
   cat <<EOF
@@ -23,12 +25,18 @@ Manage the local Yoi development stack for this checkout:
   frontend  deno run -A npm:vite@7.2.7 dev --host $FRONTEND_HOST --port $FRONTEND_PORT  (cwd: web/workspace)
 
 Actions:
-  start     stop existing listeners on the configured ports, then start runtime, backend, and frontend from this checkout
-  stop      stop runtime, backend, and frontend
-  restart   stop/start runtime and backend only; frontend is left untouched
+  start     schedule a detached job that stops existing listeners, then starts runtime, backend, and frontend from this checkout
+  stop      schedule a detached job that stops runtime, backend, and frontend
+  restart   schedule a detached job that stops/starts runtime and backend only; frontend is left untouched
   status    print pidfile and port-listener status without mutating processes
 
+By default, start/stop/restart return immediately and run in a detached job after $ACTION_DELAY_SECONDS seconds.
+This keeps API/tool-call sessions intact while the backend/runtime are restarted. Set
+YOI_DEV_WORKSPACE_FOREGROUND=1 to run the mutating action synchronously.
+
 Environment overrides:
+  YOI_DEV_ACTION_DELAY_SECONDS=60  delay before detached mutating actions run
+  YOI_DEV_WORKSPACE_FOREGROUND=1   run start/stop/restart synchronously instead of scheduling
   YOI_DEV_BACKEND_LISTEN=127.0.0.1:8787
   YOI_DEV_RUNTIME_BIND=127.0.0.1:38800
   YOI_DEV_RUNTIME_ENABLED=1        set to 0 to skip the standalone runtime process
@@ -275,8 +283,42 @@ status_all() {
   status_service frontend "$FRONTEND_PORT"
 }
 
-main() {
-  local action="${1:-}"
+schedule_detached_action() {
+  local action="$1"
+  ensure_dirs
+
+  local stamp job_log
+  stamp="$(date +%Y%m%d-%H%M%S)"
+  job_log="$LOG_DIR/${action}-$stamp.job.log"
+
+  log "scheduling $action in ${ACTION_DELAY_SECONDS}s; log: $job_log"
+  setsid bash -lc '
+    set -euo pipefail
+    delay="$1"
+    root="$2"
+    action="$3"
+    sleep "$delay"
+    cd "$root"
+    printf "[%s] dev-workspace %s starting\n" "$(date -Is)" "$action"
+    YOI_DEV_WORKSPACE_FOREGROUND=1 "$root/scripts/dev-workspace.sh" "$action"
+    status=$?
+    printf "[%s] dev-workspace %s finished with status %s\n" "$(date -Is)" "$action" "$status"
+    exit "$status"
+  ' dev-workspace-job "$ACTION_DELAY_SECONDS" "$ROOT_DIR" "$action" >>"$job_log" 2>&1 < /dev/null &
+
+  printf 'scheduled_action=%s\n' "$action"
+  printf 'scheduled_pid=%s\n' "$!"
+  printf 'scheduled_after_seconds=%s\n' "$ACTION_DELAY_SECONDS"
+  printf 'scheduled_log=%s\n' "$job_log"
+}
+
+run_mutating_action() {
+  local action="$1"
+  if [[ "$FOREGROUND_MODE" != "1" ]]; then
+    schedule_detached_action "$action"
+    return 0
+  fi
+
   case "$action" in
     start)
       start_all
@@ -287,6 +329,25 @@ main() {
     restart)
       restart_runtime_backend
       ;;
+    *)
+      printf 'unknown mutating action: %s\n' "$action" >&2
+      return 2
+      ;;
+  esac
+}
+
+main() {
+  local action="${1:-}"
+  case "$action" in
+    start)
+      run_mutating_action start
+      ;;
+    stop)
+      run_mutating_action stop
+      ;;
+    restart)
+      run_mutating_action restart
+      ;;
     status)
       status_all
       ;;