fix: propagate cancellation to scopes and awaits registered after cancel (#770)

* fix: propagate cancellation to scopes and awaits registered after cancel

Scope cancellation was a one-shot pass over the onCancel handlers: any
cancellation-aware resource registered after cancel() had already run was
never notified. As a result a nested scope created under an already
cancelled parent was born uncancelled, and an await registered in an
already cancelled scope blocked forever (the workflow got stuck).

Introduce a register-or-fire-immediately helper (addOnCancel) used by the
public onCancel(), onAwait() and createScope(); store the cancellation
reason so late handlers receive it; and guard onException()/onResult()
against a double close pass. This matches the Go/Java/TS SDKs, where
cancellation is sticky and observed at registration time.

Adds acceptance tests covering nested-scope inheritance, fail-fast await,
the public onCancel hook, and a faithful replica of the issue reproduction
(each one hangs without the fix).

Fixes #769

* test: add assertions for trailed runLocked behavior

* feat(workflow): gate cancellation propagation behind a feature flag

Make the sticky scope-cancellation behavior opt-in via
FeatureFlags::$propagateCancellationToNewScopes (default false = previous
behavior). When enabled, a nested scope, await or onCancel handler registered
after the surrounding scope was already cancelled is notified immediately
instead of being missed.

- Scope reads the flag at addOnCancel() and nextPromise().
- Acceptance suite enables it in RuntimeBuilder::init() alongside the other flags.
- Add a unit test covering both flag states.

Author: xepozz

src/Internal/Workflow/Process/Scope.php

@@ -26,6 +26,7 @@
 use Temporal\Internal\Transport\Request\Cancel;
 use Temporal\Internal\Workflow\ScopeContext;
 use Temporal\Internal\Workflow\WorkflowContext;
+use Temporal\Worker\FeatureFlags;
 use Temporal\Worker\LoopInterface;
 use Temporal\Worker\Transport\Command\RequestInterface;
 use Temporal\Workflow;
@@ -87,6 +88,8 @@ class Scope implements CancellationScopeInterface, Destroyable
 
     private bool $detached = false;
     private bool $cancelled = false;
+    private bool $closed = false;
+    private ?\Throwable $cancelReason = null;
 
     public function __construct(
         ServiceContainer $services,
@@ -191,7 +194,7 @@ public function attach(\Generator $generator): self
 
     public function onCancel(callable $then): self
     {
-        $this->onCancel[++$this->cancelID] = $then;
+        $this->addOnCancel($then);
         return $this;
     }
 
@@ -217,6 +220,7 @@ public function cancel(?\Throwable $reason = null): void
         }
 
         $this->cancelled = true;
+        $this->cancelReason = $reason;
 
         foreach ($this->onCancel as $i => $handler) {
             $this->makeCurrent();
@@ -280,12 +284,9 @@ public function always(callable $onFulfilledOrRejected): PromiseInterface
      */
     public function onAwait(Deferred $deferred): void
     {
-        $this->onCancel[++$this->cancelID] = static function (?\Throwable $e = null) use ($deferred): void {
+        $cancelID = $this->addOnCancel(static function (?\Throwable $e = null) use ($deferred): void {
             $deferred->reject($e ?? new CanceledFailure(''));
-        };
-
-        $cancelID = $this->cancelID;
-
+        });
 
         // do not cancel already complete promises
         $cleanup = function () use ($cancelID): void {
@@ -329,8 +330,7 @@ protected function createScope(
             $scope->layer = $layer;
         }
 
-        $cancelID = ++$this->cancelID;
-        $this->onCancel[$cancelID] = $scope->cancel(...);
+        $cancelID = $this->addOnCancel($scope->cancel(...));
 
         $scope->onClose(
             function () use ($cancelID): void {
@@ -371,7 +371,7 @@ protected function callSignalOrUpdateHandler(callable $handler, ValuesInterface
 
     protected function onRequest(RequestInterface $request, PromiseInterface $promise, bool $cancellable = true): void
     {
-        $this->onCancel[++$this->cancelID] = function (?\Throwable $reason = null) use ($request, $cancellable): void {
+        $cancelID = $this->addOnCancel(function (?\Throwable $reason = null) use ($request, $cancellable): void {
             $client = $this->context->getClient();
             if ($reason instanceof DestructMemorizedInstanceException) {
                 // memory flush
@@ -390,9 +390,7 @@ protected function onRequest(RequestInterface $request, PromiseInterface $promis
             }
 
             $client->request(new Cancel($request->getID()), $this->scopeContext);
-        };
-
-        $cancelID = $this->cancelID;
+        }, $cancellable);
 
         // do not cancel already complete promises
         $cleanup = function () use ($cancelID): void {
@@ -460,10 +458,27 @@ protected function next(): void
         }
     }
 
+    private function addOnCancel(callable $handler, bool $cancellable = true): int
+    {
+        $id = ++$this->cancelID;
+
+        if (FeatureFlags::$propagateCancellationToNewScopes && $this->cancelled && $cancellable) {
+            $this->makeCurrent();
+            $handler($this->cancelReason);
+            return $id;
+        }
+
+        $this->onCancel[$id] = $handler;
+        return $id;
+    }
+
     private function nextPromise(PromiseInterface $promise): void
     {
         if ($promise instanceof CancellationScopeInterface && $promise->isCancelled()) {
-            $this->handleError(new CanceledFailure(''));
+            $reason = FeatureFlags::$propagateCancellationToNewScopes && $promise instanceof self
+                ? $promise->cancelReason
+                : null;
+            $this->handleError($reason ?? new CanceledFailure(''));
             return;
         }
 
@@ -525,6 +540,11 @@ private function handleError(\Throwable $e): void
 
     private function onException(\Throwable $e): void
     {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->closed = true;
         $this->deferred->reject($e);
 
         $this->makeCurrent();
@@ -537,6 +557,11 @@ private function onException(\Throwable $e): void
 
     private function onResult(mixed $result): void
     {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->closed = true;
         $this->deferred->resolve($result);
 
         $this->makeCurrent();

src/Worker/FeatureFlags.php

@@ -64,4 +64,18 @@ final class FeatureFlags
      * @since SDK 2.17.0
      */
     public static bool $warnOnActivityMethodWithoutAttribute = true;
+
+    /**
+     * Make scope cancellation sticky: a nested scope, an await or an onCancel handler registered
+     * after the surrounding scope was already cancelled is notified immediately instead of being
+     * missed. Set to TRUE to enable this behavior.
+     *
+     * When FALSE (default), the previous behavior is kept: cancel handlers registered after the
+     * cancellation are never invoked.
+     *
+     * @experimental
+     * @since SDK 2.18.0
+     * @link https://github.com/temporalio/sdk-php/issues/769
+     */
+    public static bool $propagateCancellationToNewScopes = false;
 }

tests/Acceptance/App/RuntimeBuilder.php

@@ -88,6 +88,7 @@ public static function init(): void
         FeatureFlags::$workflowDeferredHandlerStart = true;
         FeatureFlags::$cancelAbandonedChildWorkflows = false;
         FeatureFlags::$warnOnActivityMethodWithoutAttribute = true;
+        FeatureFlags::$propagateCancellationToNewScopes = true;
     }
 
     /**