Plugin apply declared with function syntax is new-ed by the runner, discarding its returned effect - a dropped disposer leaks, a dropped promise hides the apply's failure or hang

[nokkies]

Found while chasing a consumer's silent boot hang; reproducible in ten lines against the vendored cordis in this repo.

The defect

Fiber's runner decides new versus plain call with isConstructor(runtime.callback) — a CAN-construct heuristic that any plain function declaration satisfies by owning a prototype. An object plugin whose apply is declared with function — which is what every ESM module row in a composition YAML resolves to, and the dominant idiom across this repo's own packages — is therefore constructed:

// vendor/cordis/src/fiber.ts (runner)
if (isConstructor(runtime.callback)) {
  const instance = new runtime.callback(this.ctx, this.config)
  ...
  return instance?.[symbols.init]?.()   // <- apply's actual return value is GONE
}

new apply(ctx, config) runs the body, but a returned effect becomes the new result, and the instance[init]() lookup discards it. Two consequences:

1. A returned disposer is never collected. export function apply(ctx) { return () => cleanup() } leaks its cleanup, silently, in every tree.
2. A returned promise never joins the load. The fiber turns ACTIVE while the apply is still running. Its later rejection is invisible; its hang is invisible. fiber.await(), Loader settlement, and every boot audit built on fiber state all report a healthy row.

Repro

// hang.mjs
export const name = 'hang'
export function apply() { return new Promise(() => {}) }   // never settles

Mount it as an object/namespace plugin (or as a composition row through the loader): the fiber reaches state === ACTIVE and fiber.await() resolves while the apply is pending forever. Declare the same body as apply: () => new Promise(() => {}) (arrow — no prototype) and the fiber correctly holds LOADING with a pending await. The plugin's behavior depends on which function syntax the author happened to use.

Downstream this is a silent-hang class: a composition row whose async apply sticks (a plugin bug, or a filesystem call an endpoint agent holds) passes every audit, the session composes half-applied, and the only observer left is a supervisor's process-kill timer.

The fix we adopted

Replace constructibility with authored intent: construct only class-syntax callbacks.

export function isClassSyntax(func: any): func is new (...args: any) => any {
  return typeof func === 'function' && /^class[\s{]/.test(Function.prototype.toString.call(func))
}

and at the runner, if (isClassSyntax(runtime.callback)). toString sees through proxies (the trap defaults to the target), and bound functions report function, which is right — a bound class cannot carry plugin statics anyway.

One migration note from our own tree: shape-based tracking ("{apply} never constructs", recorded at registration) looks cleaner but breaks a real pattern — our test harness wraps every plugin, classes included, as {apply: callback} and relied on the old heuristic rescuing them. The syntax rule preserves that while still fixing the drop. Second migration note: previously-discarded returns from sync function applies become honored (awaited when thenable, collected when disposable), which is the documented contract for the other plugin shapes — our full suite (14k unit tests, e2e trees) passed unchanged, but a codebase with an apply returning a non-effect value would surface it as Invalid effect at mount.

Our commit, on 0.1.1-rc.2 vintage: 7e7287d170 (private fork; happy to share the patch). On top of it we gave preset/composition mounts a deadline that reports rows still applying by id, since truthful fiber states make that audit possible at all.

[200lz]

I think the bigger invariant here is that plugin invocation kind and returned-effect semantics should be explicit, not inferred independently at execution time. Would it be worth normalizing every registered plugin into {invoke_as: class|apply, effect_contract} once at load/registration, then making Fiber state transition to ACTIVE only after that declared effect has actually settled?

[nokkies]

That is the better fix, and I think it is a strictly stronger statement of the invariant than the one I proposed.

My patch decides class vs apply at execution with a syntax predicate (/^class[\s{]/ on the function's own source), which is narrow and cheap but is still inference — it just moves the inference to a place where it happens to be right. Your framing removes the inference: if invocation kind is declared once at registration, nothing downstream has to guess, and a plugin whose shape the predicate would misread is a load-time error instead of a silent misconstruction. Given the failure mode here is silent — the returned effect is discarded and the fiber reports ACTIVE while the apply is still running — turning a guess into a declaration is worth more than making the guess more accurate.

The second half of your proposal is the part I would push hardest for, because it is what actually broke: ACTIVE only after the declared effect has settled. The construction bug was merely how the effect got dropped; the damage was that the state machine advertised a state the fiber had not reached. Any future path that drops or defers an effect reintroduces the same lie unless the transition is gated on settlement rather than on "apply returned".

Two implementation notes from carrying the narrow version in production:

• The syntax predicate has a real blind spot worth naming as motivation: a transpiled or wrapped class no longer matches ^class, so a build change can flip a plugin's invocation kind with no source change. A declared invoke_as is immune to that by construction; my version is not.
• Whatever the declaration mechanism, it needs a migration story for plugins that declare nothing. Defaulting the undeclared to today's inferred behaviour keeps existing trees loading, but the default should be visible (a load-time warning naming the plugin) or the inference just becomes permanent under a new name.

Happy to be superseded here — a declared contract is the correct shape, and my fix should be read as a stopgap for trees that need the crash to stop before that lands.

[200lz]

Thanks — agreed on treating the syntax predicate as a compatibility adapter rather than the runtime invariant.

A staged path might be:

1 Normalize every plugin at registration into an internal descriptor such as { callback, invoke_as, effect_contract, source }.
2 Let explicit declarations take precedence, while undeclared plugins retain today’s inferred behavior for compatibility.
3 Keep the legacy inference visible through a diagnostic or load-time warning when the invocation shape is ambiguous.
4 Make Fiber consume only the normalized descriptor and transition to ACTIVE only after the declared startup effect has settled.

That would allow the immediate class-syntax fix to land independently, while providing a migration path toward an invocation model that no longer depends on function shape. I’d be happy to help turn this into focused regression cases or a concrete patch if the maintainers want to pursue it.

[denial123789]

I added an English plugin-authoring note based on this report: https://sandbaseai.github.io/deepseek-harness-handbook/first-plugin.html

The guidance keeps the claim scoped: a function-shaped apply may be treated as constructible in the reported runner path, dropping a disposer or pending Promise. Test the exact composition loader, keep cleanup in ctx.effect(), and fail closed until async activation is observable.