pi-usereq 0.49.0 → 0.51.0

package/src/index.ts

@@ -1249,7 +1249,7 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
 
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the stash-assisted merge-and-delete finalization path for every matched successful worktree-backed completion even when a later busy-command rejection already moved workflow state to `error`, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` because the pi 0.67.1+ `switchSession` implementation awaits the active agent run to become idle and would deadlock inside `agent_end`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_settled` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
@@ -1373,6 +1373,13 @@ async function handleExtensionStatusEvent(
         );
       }
       if (shouldFinalizeMatchedSuccess) {
+        // Defer the restore switch, merge, and worktree deletion to
+        // `agent_settled`. The pi 0.67.1+ `switchSession` implementation
+        // awaits the active agent run to become idle before replacing the
+        // session, and that idle transition only happens at `agent_settled`.
+        // Calling `switchSession` here would deadlock the `agent_end` handler
+        // and leave the workflow parked in `merging` forever.
+        statusController.state.pendingFinalizationOutcome = outcome;
         if (debugConfig) {
           transitionPromptWorkflowState(
             statusController,
@@ -1385,75 +1392,6 @@ async function handleExtensionStatusEvent(
         } else {
           setPiUsereqWorkflowState(statusController, "merging", promptContext);
         }
-        let finalization:
-          | {
-            mergeAttempted: boolean;
-            mergeSucceeded: boolean;
-            cleanupSucceeded: boolean;
-            errorMessage?: string;
-            warningMessage?: string;
-            activeContext?: unknown;
-          }
-          | undefined;
-        try {
-          finalization = await finalizePromptCommandExecution(
-            activePromptRequest,
-            promptContext,
-            debugConfig
-              ? { config: debugConfig, workflowState: statusController.state.workflowState }
-              : undefined,
-          );
-          promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
-        } catch (error) {
-          promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
-          let errorMessage = error instanceof Error ? error.message : String(error);
-          let cleanupSucceeded = false;
-          try {
-            promptContext = (await restorePromptCommandExecution(
-              activePromptRequest,
-              promptContext,
-              debugConfig
-                ? { config: debugConfig, workflowState: statusController.state.workflowState }
-                : undefined,
-            ) ?? promptContext) as typeof ctx;
-            cleanupSucceeded = true;
-          } catch (restoreError) {
-            promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
-            errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
-          }
-          finalization = {
-            mergeAttempted: false,
-            mergeSucceeded: false,
-            cleanupSucceeded,
-            errorMessage,
-          };
-        }
-        if (
-          finalization.errorMessage
-          && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
-        ) {
-          if (debugConfig) {
-            transitionPromptWorkflowState(
-              statusController,
-              promptContext,
-              activePromptRequest.basePath,
-              debugConfig,
-              activePromptRequest.promptName,
-              "error",
-            );
-          } else {
-            setPiUsereqWorkflowState(statusController, "error", promptContext);
-          }
-          notifyContextSafely(promptContext, finalization.errorMessage, "error");
-        }
-        if (
-          finalization.warningMessage
-          && finalization.cleanupSucceeded
-          && finalization.mergeSucceeded
-          && !finalization.errorMessage
-        ) {
-          notifyContextSafely(promptContext, finalization.warningMessage, "info");
-        }
       } else if (closureFailureMessage !== undefined) {
         // Worktree-backed run that ended interrupted, failed, aborted, or
         // incomplete (REQ-209): keep the worktree execution session visible,
@@ -1500,7 +1438,7 @@ async function handleExtensionStatusEvent(
           notifyContextSafely(promptContext, error instanceof Error ? error.message : String(error), "error");
         }
       }
-      if (closureFailureMessage === undefined) {
+      if (closureFailureMessage === undefined && !shouldFinalizeMatchedSuccess) {
         statusController.state.pendingPromptRequest = undefined;
         statusController.state.activePromptRequest = undefined;
         if (debugConfig) {
@@ -1518,6 +1456,102 @@ async function handleExtensionStatusEvent(
       }
     }
   }
+  if (hookName === "agent_settled") {
+    const settledPromptRequest = statusController.state.activePromptRequest;
+    const pendingOutcome = statusController.state.pendingFinalizationOutcome;
+    if (
+      settledPromptRequest !== undefined
+      && settledPromptRequest.worktreeDir !== undefined
+      && pendingOutcome === "completed"
+    ) {
+      const debugConfig = statusController.config;
+      let promptContext = ctx;
+      let finalization:
+        | {
+          mergeAttempted: boolean;
+          mergeSucceeded: boolean;
+          cleanupSucceeded: boolean;
+          errorMessage?: string;
+          warningMessage?: string;
+          activeContext?: unknown;
+        }
+        | undefined;
+      try {
+        finalization = await finalizePromptCommandExecution(
+          settledPromptRequest,
+          promptContext,
+          debugConfig
+            ? { config: debugConfig, workflowState: statusController.state.workflowState }
+            : undefined,
+        );
+        promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
+      } catch (error) {
+        promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
+        let errorMessage = error instanceof Error ? error.message : String(error);
+        let cleanupSucceeded = false;
+        try {
+          promptContext = (await restorePromptCommandExecution(
+            settledPromptRequest,
+            promptContext,
+            debugConfig
+              ? { config: debugConfig, workflowState: statusController.state.workflowState }
+              : undefined,
+          ) ?? promptContext) as typeof ctx;
+          cleanupSucceeded = true;
+        } catch (restoreError) {
+          promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
+          errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
+        }
+        finalization = {
+          mergeAttempted: false,
+          mergeSucceeded: false,
+          cleanupSucceeded,
+          errorMessage,
+        };
+      }
+      if (
+        finalization.errorMessage
+        && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
+      ) {
+        if (debugConfig) {
+          transitionPromptWorkflowState(
+            statusController,
+            promptContext,
+            settledPromptRequest.basePath,
+            debugConfig,
+            settledPromptRequest.promptName,
+            "error",
+          );
+        } else {
+          setPiUsereqWorkflowState(statusController, "error", promptContext);
+        }
+        notifyContextSafely(promptContext, finalization.errorMessage, "error");
+      }
+      if (
+        finalization.warningMessage
+        && finalization.cleanupSucceeded
+        && finalization.mergeSucceeded
+        && !finalization.errorMessage
+      ) {
+        notifyContextSafely(promptContext, finalization.warningMessage, "info");
+      }
+      statusController.state.pendingFinalizationOutcome = undefined;
+      statusController.state.pendingPromptRequest = undefined;
+      statusController.state.activePromptRequest = undefined;
+      if (debugConfig) {
+        transitionPromptWorkflowState(
+          statusController,
+          promptContext,
+          settledPromptRequest.basePath,
+          debugConfig,
+          settledPromptRequest.promptName,
+          "idle",
+        );
+      } else {
+        setPiUsereqWorkflowState(statusController, "idle", promptContext);
+      }
+    }
+  }
   if (hookName === "session_shutdown") {
     if (shutdownPromptRequest !== undefined && statusController.config) {
       logPromptWorkflowEvent(

package/.g.conf

@@ -1,16 +0,0 @@
-{
-  "master": "master",
-  "develop": "develop",
-  "work": "work",
-  "default_commit_module": "",
-  "ver_rules": [
-    {
-      "pattern": "README.md",
-      "regex": "\\s*\\((\\d+\\.\\d+\\.\\d+)\\)\\n"
-    },
-    {
-      "pattern": "package.json",
-      "regex": "\"version\"\\s*:\\s*\"(\\d+\\.\\d+\\.\\d+)\""
-    }
-  ]
-}

package/.github/workflows/release-npm.yml

@@ -1,134 +0,0 @@
-name: Release (npm)
-
-on:
-  push:
-    tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+' # push di una versione canonica (es. v1.2.3) senza pre-release
-
-permissions:
-  contents: write
-  id-token: write  # Required for OIDC
-  attestations: write
-
-env:
-  NODE_VERSION: '24.15.0'
-
-jobs:
-  # 1. Controlla se siamo sul branch corretto
-  check-branch:
-    runs-on: ubuntu-latest
-    outputs:
-      is_master: ${{ steps.check.outputs.is_master }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0 
-
-      - name: Check if tag is on master
-        id: check
-        run: |
-          git fetch origin master
-          if git branch -r --contains ${GITHUB_SHA} | grep -q "origin/master"; then
-            echo "✅ Tag ${{ github.ref }} is on master branch. Proceeding with release."
-            echo "is_master=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "❌ Tag ${{ github.ref }} is not on master branch. Skipping release."
-            echo "is_master=false" >> "$GITHUB_OUTPUT"
-          fi
-
-  # 2. Effetua la build
-  build-release:
-    needs: check-branch
-    # Esegue questo job SOLO se l'output del job precedente è 'true'
-    if: needs.check-branch.outputs.is_master == 'true'
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0 
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v5
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          registry-url: 'https://registry.npmjs.org'
-          package-manager-cache: false  # never use caching in release builds
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build if present
-        run: npm run build --if-present
-
-      - name: Remove private package flag
-        run: npm pkg delete private
-
-      - name: Publish package to npm
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Build Changelog
-        id: build_changelog
-        uses: mikepenz/release-changelog-builder-action@v6
-        with:
-          mode: "COMMIT"
-          configurationJson: |
-            {
-              "categories": [
-               { "title": "## ⛰️ Features", "labels": ["new"] },
-               { "title": "## 🏗️ Implementations", "labels": ["implement"] },
-               { "title": "## 🐛 Bug Fixes", "labels": ["fix"] },
-               { "title": "## 🚜 Changes", "labels": ["change"] },
-               { "title": "## 🎯 Cover Requirements", "labels": ["cover"] },
-               { "title": "## ✨ Refactor", "labels": ["refactor"] },
-               { "title": "## 📚 Documentation", "labels": ["docs"] },
-               { "title": "## 🎨 Styling", "labels": ["style"] },
-               { "title": "## ◀️ Revert", "labels": ["revert"] },
-               { "title": "## ⚙️ Miscellaneous Tasks", "labels": ["misc"] },
-               { "title": "## 💬 Other", "labels": ["other"] },
-               { "title": "## ❓ Unknown", "labels": ["unknown"] },
-               { "title": "## 🚀 Release", "labels": ["release"] }
-             ],
-             "ignore_labels": [
-                "release",
-                "ignore"
-             ],
-             "transformers": [
-              {
-                "pattern": "^[^\\(:\\s]+(\\([^\\)]+\\))?!?:\\s+([\\S]+[\\s\\S]*)",
-                "target": "$2 $1"
-              }
-             ],
-             "sort": {
-                "order": "ASC",
-                "on_property": "mergedAt"
-             },
-             "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>\n\n**Full Changelog**: [#{{FROM_TAG}}...#{{TO_TAG}}](https://github.com/#{{OWNER}}/#{{REPO}}/compare/#{{FROM_TAG}}...#{{TO_TAG}})",
-              "label_extractor": [
-               {
-                 "pattern": "^([^\\(:\\s]+)(\\([^\\)]+\\))?(!)?:\\s+([\\S]+[\\s\\S]*)",
-                 "on_property": "title",
-                 "target": "$1"
-               }
-             ]
-            }
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create GitHub Release and upload assets
-        uses: softprops/action-gh-release@v2
-        with:
-          draft: false
-          prerelease: false
-          files: src/**/*
-          fail_on_unmatched_files: true
-          generate_release_notes: false
-          tag_name: ${{ github.ref_name }}
-          name: ${{github.event.repository.name}} ${{ github.ref_name }}
-          body: ${{ steps.build_changelog.outputs.changelog }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.gitignore

@@ -1,274 +0,0 @@
-##########################################
-# Exlude all files by default            #
-# (unignore rules will override this)    #
-##########################################
-/*
-*.*
-*/**
-
-##########################################
-# Include specific files and directories #
-##########################################
-!/.github/
-!/.github/workflows/
-!/.github/workflows/**/*.yml
-!/.github/workflows/
-!/.github/workflows/**/*.yaml
-!/.gitignore
-!README.md
-!CHANGELOG.md
-!WORKFLOW.md
-!TODO.md
-!LICENSE
-!LICENSE.txt
-!setup.py
-!pyproject.toml
-!pyrightconfig.json
-!uv.lock
-!.g.conf
-!package-lock.json
-!package.json
-!src/
-!src/**/*
-!docs/
-!docs/**/*
-!guidelines/
-!guidelines/**/*
-!tests/
-!tests/**/*
-!other-stuff/
-!other-stuff/**/*
-!scripts/
-!scripts/lib/
-!scripts/**/*.sh
-!scripts/**/*.ts
-!req/
-!req/docs/
-!req/docs/**/*.md
-!pi-usereq/
-!pi-usereq/docs/
-!pi-usereq/docs/**/*.md
-!pi.dev-src/
-!pi.dev-src/**/*
-!images/
-!images/**/*
-
-##########################################
-# Exlucde specific files and directories #
-##########################################
-
-# Exlude github agents and prompts
-.github/agents/
-.github/prompts/
-.github/skills/
-
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[codz]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py.cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-#poetry.toml
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-#pdm.lock
-#pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-#pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.envrc
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-# Abstra
-# Abstra is an AI-powered process automation framework.
-# Ignore directories containing user credentials, local state, and settings.
-# Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#  you could uncomment the following to ignore the entire vscode folder
-.vscode/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore
-
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
-
-# Temp dir for tests
-temp/