feat: add unified lifecycle wait support

AGENTS.md

@@ -195,11 +195,13 @@ the profile for both focused and complete live targets.
 Live e2e must strictly cover every implemented interface and command for the
 current project stage, including real create/update/delete flows when those
 commands are implemented. For Starter DB clusters, the live suite creates a
-uniquely named `tdc-e2e-*` cluster without a spending limit or explicit
-`--project-id`, verifies its project label matches the configured default, and
-deletes only that cluster. For Starter DB branches, the live suite creates, reads, lists,
+uniquely named `tdc-e2e-*` cluster with `--wait`, without a
+spending limit or explicit `--project-id`, verifies the returned state is
+`ACTIVE` and its project label matches the configured default, and deletes only
+that cluster. For Starter DB branches, the live suite creates, reads, lists,
 and deletes only a `tdc-e2e-branch-*` branch on the cluster created by the same
-test run. For Starter DB SQL access, the live suite prepares tdc-managed
+test run. Branch creation must use `--wait`; cluster deletion must
+use `--wait`. For Starter DB SQL access, the live suite prepares tdc-managed
 read-only, read-write, and admin SQL users on the temporary cluster, verifies
 connection string output, and executes the HTTPS SQL API with all three access
 modes.
@@ -317,6 +319,21 @@ Follow these rules unless `docs/priciples.md` is updated:
 - Mutating control-plane commands support `--dry-run`.
 - `--dry-run` must validate local config, credentials, provider, and region
   before reporting a planned mutation.
+- `tdc db create-db-cluster --wait` waits up to 12 minutes for the
+  created cluster to reach `ACTIVE`. It must never delete the cluster on
+  timeout, cancellation, a polling failure, or a terminal state; errors must
+  retain the created cluster ID and provide an inspection command.
+- `tdc db create-db-cluster-branch --wait` waits up to 5 minutes
+  for the created branch to reach `ACTIVE`. A failed wait must not delete or
+  recreate the accepted branch.
+- `tdc db delete-db-cluster --wait` waits up to 12 minutes and
+  succeeds when the API reports `DELETED` or the deleted cluster is no longer
+  accessible. A failed wait must state that deletion may still be in progress.
+- `tdc fs create-file-system --wait` waits up to 10 minutes for the
+  root to become readable through the public Drive9 CLI. It must retain the
+  resource and local credentials when waiting fails.
+- `tdc fs delete-file-system` is asynchronous. After Drive9 accepts deletion,
+  output status is `deleting`, not `deleted`.
 - Read-only commands reject `--dry-run`.
 - Apply `--query` after command execution and before rendering.
 - Users provide cloud placement as one canonical `region_code`, never as
@@ -374,6 +391,7 @@ Implemented command behavior:
 - `tdc organization list-projects --query 'projects[0].id'`
 - `tdc organization list-projects --output text`
 - `tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter`
+- `tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --wait`
 - `tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --dry-run`
 - `tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --project-id <project-id>`
 - `tdc db list-db-clusters`
@@ -382,8 +400,10 @@ Implemented command behavior:
 - `tdc db update-db-cluster --db-cluster-id <cluster-id> --db-cluster-name new-name`
 - `tdc db update-db-cluster --db-cluster-id <cluster-id> --monthly-spending-limit-usd-cents 1000 --dry-run`
 - `tdc db delete-db-cluster --db-cluster-id <cluster-id>`
+- `tdc db delete-db-cluster --db-cluster-id <cluster-id> --wait`
 - `tdc db delete-db-cluster --db-cluster-id <cluster-id> --dry-run`
 - `tdc db create-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-name dev`
+- `tdc db create-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-name dev --wait`
 - `tdc db create-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-name dev --dry-run`
 - `tdc db list-db-cluster-branches --db-cluster-id <cluster-id>`
 - `tdc db list-db-cluster-branches --db-cluster-id <cluster-id> --query 'branches[].id'`
@@ -404,6 +424,7 @@ Implemented command behavior:
 - `tdc db execute-sql-statement --db-cluster-id <cluster-id> --transport https --sql "select 1"`
 - `tdc db execute-sql-statement --db-cluster-id <cluster-id> --transport mysql --sql "select 1"`
 - `tdc fs create-file-system --file-system-name workspace`
+- `tdc fs create-file-system --file-system-name workspace --wait`
 - `tdc fs create-file-system --file-system-name workspace --dry-run`
 - `tdc fs create-file-system --file-system-name scratch --set-default`
 - `tdc fs delete-file-system --file-system-name workspace --confirm-file-system-name workspace`

README.md

@@ -16,7 +16,7 @@ An agent can persist state between sessions, share files across sandboxes, snaps
 1. Create a filesystem resource and get the returning token (one-time, out of the sandbox)
 
 ```shell
-export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --region <REGION_CODE> --query fs_token --output text)"
+export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --region <REGION_CODE> --wait --query fs_token --output text)"
 ```
 
 2. Mount the filesystem and use just like any regular POSIX-compliant filesystem (inside the sandbox environment)
@@ -33,29 +33,23 @@ echo "Hello Sandbox Workspace!" >> /path_to_workspace/hello.txt
 tdc fs unmount-file-system --mount-path /path_to_workspace --region <REGION_CODE>
 ```
 
-### Always-on, zero infrastructure MySQL — The 4-Command Superpower
+### Always-on, zero infrastructure MySQL — The 3-Command Superpower
 
-An agent can go from zero to live HTAP SQL (Hybrid Transaction / Analytical Processing) in four commands:
+An agent can go from zero to live HTAP SQL (Hybrid Transaction / Analytical Processing) in three commands:
 
-1. Start provisioning a serverless MySQL-compatible cluster and capture its ID
+1. Provision a serverless MySQL-compatible cluster, wait until it is active, and capture its ID
 
 ```shell
-export CLUSTER_ID="$(tdc db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --query id --output text)"
+export CLUSTER_ID="$(tdc db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait --query id --output text)"
 ```
 
-2. Wait for the cluster to become active (typically around 30 seconds)
-
-```shell
-until [ "$(tdc db describe-db-cluster --db-cluster-id "$CLUSTER_ID" --query state --output text)" = "ACTIVE" ]; do sleep 2; done
-```
-
-3. Create the SQL users it needs to connect
+2. Create the SQL users it needs to connect
 
 ```shell
 tdc db create-db-sql-users --db-cluster-id "$CLUSTER_ID"
 ```
 
-4. Retrieve the database connection string for your agent and share it across sandboxes as needed
+3. Retrieve the database connection string for your agent and share it across sandboxes as needed
 
 ```shell
 export DATABASE_URL="$(tdc db format-db-connection-string --db-cluster-id "$CLUSTER_ID" --read-write --query connection_string --output text)"
@@ -119,7 +113,7 @@ Supported regions: `aws-us-east-1` and `aws-ap-southeast-1`.
 
 ```shell
 mkdir ~/my-workspace
-tdc fs create-file-system --file-system-name my-workspace
+tdc fs create-file-system --file-system-name my-workspace --wait
 tdc fs mount-file-system --mount-path ~/my-workspace
 ```
 
@@ -136,9 +130,11 @@ tdc fs describe-file-system --file-system-name scratch
 `create-file-system` returns an file system token (`fs_token`) in its JSON result. This is the file system owner credential and should be handled as a secret. A configured machine can provision a file system and capture the token without printing the full result:
 
 ```shell
-export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --query fs_token --output text)"
+export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text)"
 ```
 
+Without `--wait`, file system creation returns after Drive9 accepts provisioning. With the flag, tdc waits up to 10 minutes until the file system root is readable through the public Drive9 data-plane CLI. A timeout or interruption leaves the file system and its locally stored credentials intact.
+
 An agent sandbox can then use that existing file system without running `tdc configure` or providing TiDB Cloud API keys:
 
 ```shell
@@ -149,11 +145,22 @@ tdc fs mount-file-system --file-system-name agent-workspace --mount-path /path_t
 ### TiDB Cloud Starter
 
 ```shell
-tdc db create-db-cluster --db-cluster-name my-distributed-mysql --db-cluster-type starter
+tdc db create-db-cluster --db-cluster-name my-distributed-mysql --db-cluster-type starter --wait
 ```
 
 Cluster creation uses the configured `project_id` by default. Use optional `--project-id <project-id>` to create in another accessible project. An explicit empty `--project-id` is rejected instead of falling back to the profile.
 
+Without `--wait`, cluster creation returns as soon as TiDB Cloud accepts the asynchronous create request. With the flag, tdc waits up to 12 minutes and returns the final `ACTIVE` cluster. A timeout or interruption leaves the created cluster intact and reports its ID for inspection.
+
+Branch creation and cluster deletion have equivalent explicit wait modes:
+
+```shell
+tdc db create-db-cluster-branch --db-cluster-id <CLUSTER_ID> --db-cluster-branch-name development --wait
+tdc db delete-db-cluster --db-cluster-id <CLUSTER_ID> --wait
+```
+
+Branch waiting lasts up to 5 minutes. Cluster deletion waiting lasts up to 12 minutes and succeeds when the API reports `DELETED` or the deleted cluster is no longer accessible.
+
 ### Organization Projects
 
 ```shell

docs/present.md

@@ -56,7 +56,8 @@ bin/tdc db create-db-cluster \
 
 bin/tdc db create-db-cluster \
   --db-cluster-name "$CLUSTER_NAME" \
-  --db-cluster-type starter
+  --db-cluster-type starter \
+  --wait
 ```
 
 从 JSON 结果中找到 cluster ID：
@@ -67,7 +68,7 @@ export CLUSTER_ID="$(bin/tdc db list-db-clusters | jq -r --arg name "$CLUSTER_NA
 bin/tdc db describe-db-cluster --db-cluster-id "$CLUSTER_ID" --output text
 ```
 
-等待状态变为 `ACTIVE`，然后更新名称并重新读取：
+创建命令返回 `ACTIVE` 后，更新名称并重新读取：
 
 ```bash
 export CLUSTER_RENAMED="${CLUSTER_NAME}-renamed"
@@ -84,7 +85,8 @@ bin/tdc db describe-db-cluster --db-cluster-id "$CLUSTER_ID" --output text
 ```bash
 bin/tdc db create-db-cluster-branch \
   --db-cluster-id "$CLUSTER_ID" \
-  --db-cluster-branch-name demo-branch
+  --db-cluster-branch-name demo-branch \
+  --wait
 
 bin/tdc db list-db-cluster-branches --db-cluster-id "$CLUSTER_ID" --output text
 ```
@@ -153,7 +155,8 @@ bin/tdc fs create-file-system \
   --dry-run
 
 bin/tdc fs create-file-system \
-  --file-system-name tdc-demo-workspace
+  --file-system-name tdc-demo-workspace \
+  --wait
 
 bin/tdc fs list-file-systems --output text
 bin/tdc fs describe-file-system \
@@ -391,7 +394,9 @@ bin/tdc fs delete-file-system \
 删除演示 cluster：
 
 ```bash
-bin/tdc db delete-db-cluster --db-cluster-id "$CLUSTER_ID"
+bin/tdc db delete-db-cluster \
+  --db-cluster-id "$CLUSTER_ID" \
+  --wait
 ```
 
 ## 讲解重点

docs/spec/done/0006-starter-db-cluster-lifecycle.md

@@ -18,6 +18,7 @@ Primary create shape:
 
 ```bash
 tdc db create-db-cluster --db-cluster-name <name> --db-cluster-type starter
+tdc db create-db-cluster --db-cluster-name <name> --db-cluster-type starter --wait
 ```
 
 ## Behavior
@@ -28,9 +29,22 @@ tdc db create-db-cluster --db-cluster-name <name> --db-cluster-type starter
 - Use long flags only.
 - Mutating commands support `--dry-run`.
 - Commands must not prompt.
+- Create returns after the API accepts the asynchronous request by default.
+  Optional `--wait` polls the created cluster until it reaches
+  `ACTIVE`, for up to 12 minutes, and returns the final cluster representation.
+- Waiting never deletes the created resource. Timeout, cancellation, polling
+  failure, or a terminal `DELETING`, `DELETED`, or `INACTIVE` state returns an
+  actionable error that includes the cluster ID and an inspection command.
 - Delete must be non-interactive. It reads the remote cluster first, validates
   Starter-only behavior when plan metadata is available, and then deletes by
   cluster ID; it must never prompt.
+- Delete returns after the API accepts the asynchronous request by default.
+  Optional `--wait` polls for up to 12 minutes and succeeds when
+  the cluster reaches `DELETED` or is no longer accessible after the accepted
+  delete request.
+- A delete wait timeout, cancellation, or polling failure must not submit
+  another delete request. The error states that deletion may still be in
+  progress and identifies the cluster.
 
 ## Inputs And Config
 
@@ -50,7 +64,12 @@ tdc db create-db-cluster --db-cluster-name <name> --db-cluster-type starter
   fields internally.
 - Create and update return the remote resource representation or operation
   status returned by the API.
-- Delete returns a structured confirmation or operation status.
+- Create with `--wait` returns a cluster whose state is `ACTIVE`.
+  If waiting fails after creation, the error states that the cluster remains
+  allocated and includes its ID.
+- Delete returns a structured confirmation or operation status. With
+  `--wait`, it returns a cluster representation with state
+  `DELETED`.
 - Errors should distinguish validation failures, authentication failures,
   permission failures, not found, quota/capacity issues, and backend API errors.
 - Permission errors must name the required permission, such as
@@ -64,10 +83,12 @@ and region:
 ```bash
 tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --dry-run
 tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter
+tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --wait
 tdc db create-db-cluster --db-cluster-name demo --db-cluster-type starter --project-id <project-id>
 tdc db list-db-clusters --query 'clusters[].id'
 tdc db describe-db-cluster --db-cluster-id <id>
 tdc db delete-db-cluster --db-cluster-id <id>
+tdc db delete-db-cluster --db-cluster-id <id> --wait
 ```
 
 No command asks for a server URL. The active profile's `cloud_provider` and
@@ -108,6 +129,10 @@ Command mapping:
      and set label `tidb.cloud/project`.
   3. Call `POST /v1beta1/clusters` with `displayName`, project label, region
      name such as `regions/aws-us-east-1`, and only other confirmed fields.
+  4. When `--wait` is set and the create response is not already
+     `ACTIVE`, call `GET /v1beta1/clusters/{clusterId}` every two seconds until
+     `ACTIVE`, a terminal state, cancellation, polling failure, or the
+     12-minute deadline.
 - `tdc db describe-db-cluster`
   1. Call `GET /v1beta1/clusters/{clusterId}` with optional `view`.
   2. If the returned cluster exposes `clusterPlan` and it is not `STARTER`,
@@ -123,6 +148,10 @@ Command mapping:
   2. Call `GET /v1beta1/clusters/{clusterId}`.
   3. If `clusterPlan` is present, verify it is `STARTER`.
   4. Call `DELETE /v1beta1/clusters/{clusterId}`.
+  5. When `--wait` is set, call
+     `GET /v1beta1/clusters/{clusterId}` every two seconds until the state is
+     `DELETED`, the resource is no longer accessible, cancellation, polling
+     failure, or the 12-minute deadline.
 
 Available but not part of this lifecycle MVP:
 
@@ -145,14 +174,21 @@ Available but not part of this lifecycle MVP:
 ## Acceptance Criteria
 
 - Mock API tests cover create/list/describe/update/delete.
+- Mock API tests cover wait success, an immediately active create response,
+  terminal state, polling failure, timeout, and default non-wait behavior.
+- Delete wait tests cover `DELETING` to `DELETED`, inaccessible-after-delete,
+  timeout, and dry-run wait-plan reporting.
 - Tests cover required `--db-cluster-type starter` on create.
-- Tests cover dry-run request validation without sending mutating requests.
+- Tests cover dry-run request validation and wait-plan reporting without
+  sending mutating requests.
 - Tests cover stable JSON output and `--query`.
 - Tests cover delete safety behavior without prompts.
 - `make live-e2e` covers the real cluster lifecycle: create a uniquely named
-  `tdc-e2e-*` Starter cluster without a spending limit, read it, update it,
-  read it again, delete it, and verify the cluster becomes deleted or not
-  found. The cleanup path only deletes the cluster created by that test run.
+  `tdc-e2e-*` Starter cluster with `--wait` and without a spending
+  limit, verify the create result is `ACTIVE`, read it, update it, read it
+  again, delete it with `--wait`, and verify the returned state
+  is `DELETED`. The cleanup path only deletes the cluster created by that test
+  run and also uses the wait flag.
 
 ## Out Of Scope
 

docs/spec/done/0007-starter-db-branch-lifecycle.md

@@ -20,6 +20,12 @@ Initial command set:
 - Mutating branch commands support `--dry-run`.
 - Commands must not prompt.
 - Branch operations require explicit cluster identification.
+- Create returns after the API accepts the asynchronous request by default.
+  Optional `--wait` polls the created branch for up to five
+  minutes and returns the final `ACTIVE` branch.
+- A branch wait timeout, cancellation, polling failure, or terminal `DELETED`
+  state leaves the accepted branch unchanged and returns an actionable error
+  containing both cluster and branch IDs.
 - Delete is non-interactive and deletes by explicit cluster ID plus branch ID
   after reading the remote branch.
 
@@ -36,7 +42,8 @@ Use only fields supported by the Starter branch API.
 ## Output And Errors
 
 - JSON is the default output.
-- Branch create returns the branch resource or operation status.
+- Branch create returns the branch resource or operation status. With
+  `--wait`, it returns a branch whose state is `ACTIVE`.
 - Not-found errors should identify whether the missing object is the cluster or
   the branch.
 - Permission errors must name the required permission, such as
@@ -48,6 +55,7 @@ Users can manage Starter branch workflows without adding another command level:
 
 ```bash
 tdc db create-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-name dev --dry-run
+tdc db create-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-name dev --wait
 tdc db list-db-cluster-branches --db-cluster-id <cluster-id>
 tdc db describe-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-id <branch-id>
 tdc db delete-db-cluster-branch --db-cluster-id <cluster-id> --db-cluster-branch-id <branch-id>
@@ -84,6 +92,10 @@ Command mapping:
   1. Validate `--db-cluster-id` and API-backed branch fields such as
      `--db-cluster-branch-name`.
   2. Call `POST /v1beta1/clusters/{clusterId}/branches`.
+  3. When `--wait` is set, call
+     `GET /v1beta1/clusters/{clusterId}/branches/{branchId}` every two seconds
+     until `ACTIVE`, terminal `DELETED`, cancellation, polling failure, or the
+     five-minute deadline.
 - `tdc db describe-db-cluster-branch`
   1. Call `GET /v1beta1/clusters/{clusterId}/branches/{branchId}`.
 - `tdc db delete-db-cluster-branch`
@@ -110,13 +122,16 @@ Available but out of scope for this spec:
 ## Acceptance Criteria
 
 - Mock API tests cover create/list/describe/delete.
+- Mock API tests cover branch wait success, terminal state, polling failure,
+  timeout, and dry-run wait-plan reporting.
 - Tests cover required cluster identification.
 - Tests cover dry-run for create and delete.
 - Tests cover branch not-found errors.
 - Tests cover `--query` over list output.
-- `make live-e2e` creates a temporary `tdc-e2e-branch-*` branch on the
-  temporary `tdc-e2e-*` Starter cluster, then lists, describes, deletes, and
-  verifies deletion for that branch without touching pre-existing branches.
+- `make live-e2e` creates a temporary `tdc-e2e-branch-*` branch with
+  `--wait` on the temporary `tdc-e2e-*` Starter cluster, asserts
+  the returned state is `ACTIVE`, then lists, describes, deletes, and verifies
+  deletion without touching pre-existing branches.
 
 ## Out Of Scope