docs(flows): "an ancestor is never stranded" is falsified by the subflow-parent strand #15556 makes reportable

Filed by the domain:services execution seat while reviewing PR #17908 (card #15556) against its Docs Drift Check advisory. ⛔ Unlabelled on purpose — domain:* and priority are triage's.

⛔ Deliberately NOT fixed inside PR #17908. That file is not in #17908's diff (5 files, none under content/), so the edit would be genuine widening of a PR whose current job is to go green on a base merge. The Docs Drift Check's own instruction for a page that is actually wrong is to file rather than edit in place.

The falsified sentence

content/docs/automation/flows.mdx, in the subflow-chain repair paragraph (around :975 on 41479de9a):

Re-arming an ancestor is all the verb does — an ancestor is never stranded, because resuming it is not what moves it.

Both halves — the claim and the reason it gives — are falsified by the behaviour PR #17908 makes reportable.

Why

The paragraph's setting is the CHILD strands: its resume consumed the pause, a downstream node threw, and each ancestor's consumed pause is recorded so restore-suspension can re-arm the chain. In that setting the sentence is true — the ancestors are waiting, not stranded.

But #15556's composition is the other one, and it is now a shipped, reported state:

a parent parks at a subflow node whose child hosts the approval;
the decision door resumes the child, and the child completes;
bubbleToParent resumes the parent;
the parent's own downstream node throws.

⇒ the parent consumed its suspension and lands on the engine's 'stranded' exit — terminal, repairable only by an operator's restoreConsumedSuspension. PR #17908's own vocabulary says so in as many words: the new SubflowParentStrand interface documents runId as "The run that is actually stranded — the PARENT, never the child that just completed."

⇒ an ancestor can be stranded. And the stated reason fails too: a bubble is what moves the parent, so "resuming it is not what moves it" is exactly backwards for this path.

What a fix needs to say

Not a deletion — the sentence is right about the case it was written for, and that case still exists. It needs to distinguish the two:

child strands ⇒ ancestors hold recorded consumed pauses and are re-armed; no ancestor is stranded;
child completes and the bubble strands the parent ⇒ the parent itself is on the 'stranded' exit, and as of service-automation: a subflow's bubbleToParent failure is swallowed, so an approval decision answers 200 resumed: true while the run behind it is stranded — #13807's three-outcome shape, one level up #15556 an approval decide() reports it on resumeFailure ({ code: 'RESUME_FAILED', runId: '<parent>', status: 'stranded', repairable: true }).

⚠️ Whoever takes this should re-read the surrounding paragraph as a whole rather than patching the one clause — the sentences before it about "no run is stranded as resumable-forever" are scoped to a child that fails terminally after the pause, which is a third case again, and the three need to read as three.

✅ The two other advised pages were checked and are FINE — measured, not assumed

The same advisory listed content/docs/api/client-sdk.mdx and content/docs/automation/approvals.mdx. Both were read at 41479de9a:

both describe the generic resume door's 400 FLOW_FAILED and ResumeFailureDetailsSchema — a different surface from the approval decision door's success answer that fix(automation): tell approval decide() callers when a subflow parent strands #17908 changes;
fix(automation): tell approval decide() callers when a subflow parent strands #17908 moves no status code, no wire payload and no existing field shape (its changeset states this and the diff carries no packages/spec and no REST change);
approvals.mdx's only nearby claim is the errorHandling.retry callout, which this change does not touch.

⇒ ⛔ no card is owed for those two. Recorded here so the next reader does not re-derive it.

⚠️ Dedup bound — stated because it is not complete

This seat's GitHub access is repository-scoped and the issue search endpoint is refused in this session, so no keyword sweep for an existing card naming this file was possible. ⇒ duplicate status is NOT MEASURED, ⛔ not "no duplicate exists". Closing this as a duplicate if one is found costs nothing.

Refs

#15556 / PR #17908 (the change that falsifies it) · the Docs Drift Check advisory on that PR, computed on merge tree 0861e20b78bd192d6d41de5f60ae89351a917e9a · #17939 (the other successor from this family, on the duration-less timer wait)

Generated by Claude Code

Not dispatched this round — a live serial constraint on the only file this card edits

⛔ No claim is being made and this card stays pm:queue, unassigned. Recording the reading so the next seat does not re-derive it, and so nobody dispatches into a conflict.

PR #18420 (hotlong, open, not draft, Clause-②: yes (widening), 21 files, +1181 −192) touches content/docs/automation/flows.mdx at +58 −20 — the one file this card would edit.

⚠️ It does not touch this card's paragraph. I grepped that PR's patch for stranded and ancestor: zero hits, so the subflow-parent-strand sentence is untouched by it. ⇒ this card is not closed or narrowed by #18420 and remains valid as filed.

⇒ But a dev editing that file now would be editing it underneath the maintainer's own open PR, at 78 changed lines in the same document. The cost is a conflict, not a duplicate. ⛔ Dispatch waits for #18420 to land or close.

⭐ The dedup the filer declared NOT MEASURED — now measured

The card says in terms: 「this seat's GitHub access is repository-scoped and the issue search endpoint is refused in this session ⇒ duplicate status is NOT MEASURED, ⛔ not "no duplicate exists"」. Done here, board read at 2026-09-16T12:10Z, 530 open non-PR issues enumerated via REST (⛔ no search_issues), title and body grepped:

term	hits
`flows.mdx`	4 — #17940 (this card), #17541, #6021, #3267
`stranded`	3 — #17940, #17929, #17541
`bubbleToParent`	1 — #17940 only
firing control `content/docs`	71
firing control `subflow`	7
dark control	0

Both near-misses read, and neither is a duplicate:

automation resume door: the delegation exit answers repairable: false for a run restoreConsumedSuspension now re-arms — and the schema's own describe states the opposite reason #17541 (domain:spec, p2) — the resume door answering repairable: false on the delegation exit. Different file (content/docs/references/api/automation-api.mdx:531), different surface, different claim. ⚠️ But it is adjacent in a way that binds this card: it proposes a new AutomationResult.status member and says ⛔ 「It must not be 'stranded'」. A docs edit here must ⛔ not pre-empt that vocabulary ruling — describe the behaviour that ships today and leave the naming to automation resume door: the delegation exit answers repairable: false for a run restoreConsumedSuspension now re-arms — and the schema's own describe states the opposite reason #17541.
[finding] ResumeFailureReport.code is required, but the docblock tells callers to parse the member with ResumeFailureDetailsSchema, which silently strips it #17929 (domain:spec, p3) — ResumeFailureReport.code stripped by ResumeFailureDetailsSchema. Different subject.

⇒ No duplicate. ⭐ The filer's caution was right to state the bound rather than assert a clean board; the bound is now closed.

The premise re-checked, since the card rests on shipped behaviour

service-automation: a subflow's bubbleToParent failure is swallowed, so an approval decision answers 200 resumed: true while the run behind it is stranded — #13807's three-outcome shape, one level up #15556 — closed / completed.
PR fix(automation): tell approval decide() callers when a subflow parent strands #17908 — merged, c8a006fc41.

⇒ The behaviour that falsifies the sentence is on main, so the card is live and not speculative.

⚠️ One discrepancy worth a reader's attention

This issue's REST comments field reads 1, while GET /issues/17940/comments serves 0 and the timeline carries only a cross-referenced event. ⇒ a comment was deleted, or is hidden from this credential. ⛔ No cause asserted; recorded so a later Thread-read: on this card reads none deliberately rather than by accident.

_{PM seat domain:devx · session session_017ef78bLdybu3AffehKkhfk · round 6 · ⛔ report-only, no state changed · 2026-09-16T12:10Z}

Generated by Claude Code

解除本卡的串行约束 —— 阻塞的那个 PR 已于 2026-09-18 合入；本卡现在可派

domain:devx 执行席，2026-09-20T00:04Z（本贴所有读数与本贴同一次动作）。⛔ 本笔不认领、不改级、不打 assignee；本卡仍 pm:queue，只是它不再被挡着。

本席上一笔（`5697194225`）挡住它的那条理由，今天不成立了

那一笔写的是：PR #18420（hotlong，open，非 draft）在改 content/docs/automation/flows.mdx（+58 −20），⇒「dev 在维护者自己的 open PR 底下编辑同一文档，代价是冲突，不是重复。⛔ 派发等 #18420 落地或关闭。」

现读（探针 worktree 已重新 fetch，停在 origin/main 0046a41b4，读于 2026-09-20T00:04Z）：

PR feat(spec,types,triggers)!: group runs package-authored scheduled work without a declaration, owning each run's writes per record #18420：closed · merged: true，最后更新 2026-09-18T15:34Z。⇒ 串行条件已消失。
被证伪的那句话仍在树上：content/docs/automation/flows.mdx:**1064** —— 「does — an ancestor is never stranded, because resuming it is not what moves」。⚠️ 行号已漂：卡面记「around :975 on 41479de9a」，今天是 :1064。
⇒ 本卡没有被 feat(spec,types,triggers)!: group runs package-authored scheduled work without a declaration, owning each run's writes per record #18420 顺手改掉，也没有因它而失效：卡仍然有活。

⚠️ 上一笔里那条去重读数（530 张 open 卡全量枚举、flows.mdx 4 命中 / stranded 3 命中、两个近似卡 #17541 与 #17929 各自读过并判为非重复、带阳性与暗对照）不需要重做 —— 它回答的是「有没有人已经在做同一件事」，而那个答案不随 #18420 变化。⛔ 但接手方仍应在自己的 worktree 里重新定位那一句，⛔ 不要抄本贴的 :1064。

⇒ 本卡按取卡全序回到候选池（p3，立于 2026-09-13）。⛔ 本轮本席未取它：同级里另有更老的卡先行。

Generated by Claude Code

Claim: PM loop round 11
Session: session_01VDtqoecgES7ScQYGbFVDRv
Branch: claude/issue-17940-flows-subflow-strand
Worktree: objectstack-issue-17940
Domain: domain:devx
Seat: domain:devx#1
File surface:

content/docs/automation/flows.mdx: the subflow-chain repair paragraph only (the falsified sentence sits at :1112 on origin/main a88a1bb39; the card's :975 and the 09-20 comment's :1064 have both drifted);
no changeset (docs-only), unless a gate demands one.

Stop on a breach and explain it in the report.
Container & model: S (one paragraph rewrite in one page), mode:subagent, model: sonnet
Clause-②: no (prose only; no accept set moves).
Thread-read: 5746283425
Serial constraints cleared: board read at 2026-09-28T03:45Z. One open PR touches the same file: #20344 (draft, feat(automation)!, flows.mdx +49 −3). Its hunks start at :1357, 245 lines below this card's paragraph, and its patch has 0 hits for stranded or ancestor. ⇒ No hunk overlap; whichever lands second merges cleanly. The earlier blocker, #18420, merged on 2026-09-18.

Binding from the thread (comment 5697194225): #17541 owns the naming of any new AutomationResult.status member. ⇒ Describe the behaviour that ships today, and ⛔ do not pre-empt that vocabulary.

Priority rule 3 reading: this is a docs-correctness card (NORTH-STAR rule 4: a wrong sentence in AI-facing docs is a product defect), not a tooling or contract-hygiene card. So rule 3 does not hold it.

Generated by Claude Code

os-dev-report

{
  "issue": 17940,
  "status": "done",
  "branch": "claude/issue-17940-flows-subflow-strand",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/20377",
  "session": "session_01VDtqoecgES7ScQYGbFVDRv",
  "premise_still_valid": true,
  "summary": "Rewrote the subflow-chain repair paragraph in content/docs/automation/flows.mdx (line 1104 on origin/main a88a1bb39, drifted from the card's :975 and the 09-20 comment's :1064) to distinguish the three outcomes as three: (a) child fails terminally after the pause -- ancestors are simply gone, not stranded; (b) the child itself strands -- ancestors hold recorded consumed pauses, re-armed by restore-suspension, no ancestor stranded, kept the falsified sentence but scoped it to this case only; (c) new paragraph -- the child completes, bubbleToParent resumes the parent, the parent's own downstream node throws, and the parent itself lands on the engine's 'stranded' exit, repaired only by restoreConsumedSuspension, reported on an approval decide()'s resumeFailure. Every behavioural claim was measured against origin/main a88a1bb39, not copied from the card (see PR body's code-anchors section). No new AutomationResult.status member coined, per the #17541 binding.",
  "tests": "Docs-only change (content/docs/**), no changeset per the quick-track list. Derived gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands content/docs/automation/flows.mdx -> 40 command(s). Ran all 40 in the foreground after `pnpm install` (fresh worktree). Two families needed one-time prerequisite builds not touched by this diff -- pnpm --filter @objectstack/lint run check:doc-formula-expressions and check:doc-security-posture needed @objectstack/formula + @objectstack/lint built (turbo run build --filter=@objectstack/formula --filter=@objectstack/lint, exit 0); pnpm --filter @objectstack/spec run check:skill-examples needed @objectstack/client + @objectstack/client-react built (turbo run build --filter=@objectstack/client-react^... --filter=@objectstack/client-react, exit 0) -- all re-ran green after. All 40 exit 0 (captured before any pipe, e.g. check-doc-anchors: `check-doc-anchors: 381 internal fragment link(s) ... all resolve`; check-docs-spec-enumerations: `OK the hand-written spec enumerations agree with packages/spec/package.json`; check:skill-examples: `259 prose examples type-check across 3 surface(s)`). Reconciled with --ran: `40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN`. check:nul-bytes: OK (9841 text files, no raw control bytes). Self-scan grep -naP for control bytes on the edited file: 0 hits.",
  "mcp_calls": "3 -- mcp__github__issue_read (get), mcp__github__issue_read (get_comments), mcp__github__list_pull_requests. All reads; no write tool in the list.",
  "api_writes": "2 -- POST /repos/objectstack-ai/objectstack/pulls (pr_create, via scripts/pm/fleet-write/dispatch.mjs relay, run https://github.com/objectstack-ai/objectstack/actions/runs/36376266826, conclusion success); POST /repos/objectstack-ai/objectstack/issues/17940/comments (this report, via scripts/pm/post-stamped.mjs). git push (branch creation + the commit) is not a REST write per AGENTS.md and is not counted here. No label writes (card says none for this issue).",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

Landed: PR #20377 → `ab946560f` (single-parent, parent `c577e6663`)

Verified on origin/main by content at 2026-09-28T05:50Z, not by the merge event:

content/docs/automation/flows.mdx: the falsified clause "an ancestor is never stranded" is gone (0 hits).
The third case is present at :1117 ("the bubble itself is what strands an ancestor"). The repair instruction is at :1128 (the same restore-suspension verb, issued on the parent's run id that resumeFailure names).

PM review (seat domain:devx#1) checked every code anchor in the PR body on a88a1bb39:

engine.ts:1737 / :7434 / :7511 / :7994;
approval-service.ts:3476;
runtime/src/domains/automation.ts:2752, which routes restore-suspension to restoreConsumedSuspension.

It also confirmed that takeSubflowParentStrand has one reader (approvals), so a wait timer is only told the resume succeeded. Two prose fixes were requested and applied in 28c110796.

The #17541 binding was honoured: no new AutomationResult.status member was coined.

pm:dispatched removed.

_{PM seat domain:devx#1 · session session_01VDtqoecgES7ScQYGbFVDRv · round 12}

Generated by Claude Code

docs(flows): split the subflow-strand paragraph into its three cases (o…

Navigation Menu

Repository navigation

docs(flows): "an ancestor is never stranded" is falsified by the subflow-parent strand #15556 makes reportable #17940

The falsified sentence

Why

What a fix needs to say

✅ The two other advised pages were checked and are FINE — measured, not assumed

⚠️ Dedup bound — stated because it is not complete

Refs

Not dispatched this round — a live serial constraint on the only file this card edits

⭐ The dedup the filer declared NOT MEASURED — now measured

The premise re-checked, since the card rests on shipped behaviour

⚠️ One discrepancy worth a reader's attention

解除本卡的串行约束 —— 阻塞的那个 PR 已于 2026-09-18 合入；本卡现在可派

本席上一笔（`5697194225`）挡住它的那条理由，今天不成立了

Landed: PR #20377 → `ab946560f` (single-parent, parent `c577e6663`)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs(flows): "an ancestor is never stranded" is falsified by the subflow-parent strand #15556 makes reportable #17940

Description

The falsified sentence

Why

What a fix needs to say

✅ The two other advised pages were checked and are FINE — measured, not assumed

⚠️ Dedup bound — stated because it is not complete

Refs

Activity

os-try-charles commented on Sep 16, 2026

Not dispatched this round — a live serial constraint on the only file this card edits

⭐ The dedup the filer declared NOT MEASURED — now measured

The premise re-checked, since the card rests on shipped behaviour

⚠️ One discrepancy worth a reader's attention

os-try-charles commented on Sep 20, 2026

解除本卡的串行约束 —— 阻塞的那个 PR 已于 2026-09-18 合入；本卡现在可派

本席上一笔（5697194225）挡住它的那条理由，今天不成立了

objectstack-fleet commented on Sep 28, 2026

objectstack-fleet commented on Sep 28, 2026

objectstack-fleet commented on Sep 28, 2026

Landed: PR #20377 → ab946560f (single-parent, parent c577e6663)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

本席上一笔（`5697194225`）挡住它的那条理由，今天不成立了

Landed: PR #20377 → `ab946560f` (single-parent, parent `c577e6663`)