Git workspace scanner produces no diagnostic output when it fails or finds nothing

[JoshuaRowePhantom]

Summary

GitWorkspaceScanTool and GitWorkspaceDiscoveryTool swallow all errors silently and
produce no observable output — no log messages, no result summary, no per-run status on
the tool-relationship entity. When the tool does not discover repositories there is no
way to determine whether it ran, what it scanned, what it skipped, or why it produced no
results.

Missing diagnostics

No logger

Neither GitWorkspaceScanTool nor GitWorkspaceDiscoveryTool accepts an
ILogger / ILoggerFactory. All exception paths and intermediate states are invisible.

Swallowed exceptions with no trace

GitWorkspaceScanTool.GetLocalFixedDriveRoots:

catch (IOException)
{
    return [];    // no log; caller cannot tell drives failed to enumerate
}

GitWorkspaceScanTool.EnumerateGitRepositories:

catch (Exception exception) when (exception is IOException or UnauthorizedAccessException)
{
    continue;     // no log; unknown how many directories were skipped
}

GitWorkspaceDiscoveryTool.DiscoverGitWorktreePaths:

catch (Exception exception) when (exception is UnauthorizedAccessException or DirectoryNotFoundException or IOException)
{
    continue;     // same problem
}

GitWorkspaceDiscoveryTool.GetGitMetadata:

catch (RepositoryNotFoundException) { return new GitMetadata(); }
catch (LibGit2SharpException)       { return new GitMetadata(); }
// both silent; no indication which repo failed LibGit2 open

WorkspaceToolExecutionResult carries no summary

WorkspaceToolExecutionResult has no fields for:

• Repos found / skipped counts
• Directories scanned
• Errors encountered
• Scan roots actually used

The caller (ScheduledToolHost) has no data to surface to the user or persist on the
entity.

tool-relationship entity not updated with run outcome

ScheduledToolHost stamps last-started before the run but never writes a
last-result, last-error, or repositories-found field back to the entity after
completion. There is no way to inspect the outcome of the last run without attaching a
debugger.

Proposed fixes

1. Inject ILogger<GitWorkspaceScanTool> (and similarly for
   GitWorkspaceDiscoveryTool). Log:

   • Information: scan roots resolved, scan started/completed, repo count
   • Warning: drive enumeration failed, individual directory access denied (once per
     root, not per directory to avoid log spam)
   • Error: data layer write failure

2. Add result fields to WorkspaceToolExecutionResult:

   public int RepositoriesFound { get; init; }
   public int DirectoriesSkipped { get; init; }
   public IReadOnlyList<string> ScanRootsUsed { get; init; }
   public string? ErrorSummary { get; init; }

3. Persist run outcome on tool-relationship entity. After each run,
   ScheduledToolHost writes the result summary to fields such as
   last-result-repositories-found, last-result-error so it is visible in the UI and
   queryable from the database.

4. Surface scan roots actually used in the result so operators can confirm the tool
   is scanning the expected paths.

Affected files

• Phantom.Workspaces/Tools/GitWorkspaceScanTool.cs
• Phantom.Workspaces/Tools/GitWorkspaceDiscoveryTool.cs
• Phantom.Workspaces/ScheduledTools/ScheduledToolHost.cs
• Phantom.Workspaces.Data.Core/JsonSchemas/tool-relationship.json

[JoshuaRowePhantom]

Most exceptions during scanning are not reportable errors. There are many files the user will not have access to. Don't report these.

However, exceptions during scanning a top-level drive are probably reportable.

[JoshuaRowePhantom]

Option #2 isn't good because most tools won't have those results. Option #1 is good so that we can collected detailed information from a running process. Don't we already have a workspace tool result entity type that such log lines can be added to?

[JoshuaRowePhantom]

Thanks for the feedback. Here is the revised approach:

Revised proposal

Exception reporting: drive-level only

Per-directory IOException / UnauthorizedAccessException during recursive scan are expected and will not be logged — the user routinely lacks access to many directories. However, a failure to enumerate the drives themselves (top-level IOException in GetLocalFixedDriveRoots) is unexpected and should be logged as a Warning, since it means the tool may have scanned nothing at all.

// GetLocalFixedDriveRoots — log the drive-level failure
catch (IOException ex)
{
    this.logger.LogWarning(ex, "Failed to enumerate fixed drives; scan may be incomplete.");
    return [];
}

// EnumerateGitRepositories / DiscoverGitWorktreePaths — stay silent on per-directory errors
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
    continue; // expected; no log
}

GetGitMetadata RepositoryNotFoundException / LibGit2SharpException failures can be logged at Debug level (they indicate a path that looked like a repo but is not).

Drop WorkspaceToolExecutionResult field additions (option 2)

Agreed — WorkspaceToolExecutionResult is shared across all tools and should not carry git-specific fields. Dropping that part of the proposal.

Use tool-execution-result entity for persisted diagnostics

The existing tool-execution-result schema already supports content (documented in tool-execution-result-schema.md) and allows child result entities for sub-tasks / incremental progress. The git scanner should write its diagnostic summary into the result entity's content field:

{
  "entity-types": ["entity", "tool-execution-result"],
  "tool-name": "git-workspace-scan",
  "start-time": "...",
  "end-time": "...",
  "status": "succeeded",
  "content": {
    "default": {
      "mime-type": "text/plain",
      "text": "Scanned 3 roots. Found 12 repositories. 1 drive enumeration warning (see log)."
    }
  }
}

This keeps the diagnostic data in the natural place (the run record), is visible in the tools view, and does not require schema changes to tool-relationship or WorkspaceToolExecutionResult. ILogger remains the mechanism for detailed in-process output; content on the result entity is the persisted human-readable summary.

Summary of changes

Item	Decision
ILogger<GitWorkspaceScanTool> / ILogger<GitWorkspaceDiscoveryTool>	✅ Add
Log per-directory access errors	❌ Remove
Log drive enumeration failure	✅ Warning
Log GetGitMetadata LibGit2 failures	✅ Debug
Add fields to WorkspaceToolExecutionResult	❌ Remove
Add fields to tool-relationship	❌ Remove
Write summary to tool-execution-result content	✅ Add

[JoshuaRowePhantom]

Design - adding loggers and diagnostic summary to git scanner tools

[JoshuaRowePhantom]

Tests

• GitWorkspaceScanTool: ExecuteAsync_WhenDriveEnumerationFails_LogsWarning — verifies ILogger.LogWarning is called with exception when GetLocalFixedDriveRoots throws IOException
• GitWorkspaceScanTool: ExecuteAsync_ReturnsResultContentWithScanSummary — verifies ResultContent on the returned result contains repo count and scan root
• GitWorkspaceDiscoveryTool: ExecuteAsync_WhenGetGitMetadataFails_LogsDebug — verifies ILogger.LogDebug is called when a repo path fails to open via LibGit2

[JoshuaRowePhantom]

Design - adding loggers and diagnostic summary to git scanner tools

Root cause / approach

Both GitWorkspaceScanTool and GitWorkspaceDiscoveryTool swallow errors silently and produce no observable output. The fix adds ILogger to each tool and writes a human-readable diagnostic summary to the ool-execution-result entity's content field.

Design decisions

Exception handling scope: Per the discussion in comments, per-directory IOException/UnauthorizedAccessException during recursive scan are expected (user lacks access to many directories) and are NOT logged. Only failures at the drive-enumeration level (i.e., the provider call that resolves scan roots) are logged as Warning, since that would mean the tool scanned nothing at all.

Logger injection: ILogger? and ILogger? are added as optional constructor parameters defaulting to NullLogger.Instance, preserving the zero-argument constructor used throughout existing tests.

Diagnostic summary: WorkspaceToolExecutionResult gains a ResultContent property (a nullable string). GitWorkspaceScanTool.ExecuteAsync sets it to a plain-text summary like Scanned 1 root(s) [C:\]. Found 12 repositories. ScheduledToolHost.RunToolAsync passes
esult.ResultContent ?? result.ErrorMessage as the content to ToolExecutionResultWriter.CompleteAsync, which writes it to the ool-execution-result entity's content.default.text field — the natural place for run diagnostics, already supported by the schema.

Drop WorkspaceToolExecutionResult field additions and ool-relationship changes: As agreed in comments, git-specific fields are not added to WorkspaceToolExecutionResult or ool-relationship. The summary goes into the ool-execution-result entity's content field instead.

Files changed

• Phantom.Workspaces/Tools/GitWorkspaceScanTool.cs — inject logger, catch drive-level IOException in ResolveScanRoots and log Warning, return ResultContent summary
• Phantom.Workspaces/Tools/GitWorkspaceDiscoveryTool.cs — inject logger, log Debug for RepositoryNotFoundException/LibGit2SharpException in GetGitMetadata
• Phantom.Workspaces/Tools/WorkspaceToolExecutionResult.cs — add ResultContent property
• Phantom.Workspaces/ScheduledTools/ScheduledToolHost.cs — pass
  esult.ResultContent ?? result.ErrorMessage as content
• Phantom.Workspaces/Phantom.Workspaces.csproj — add Microsoft.Extensions.Logging.Abstractions reference
• Directory.Packages.props — add Microsoft.Extensions.Logging.Abstractions version
• Phantom.Workspaces.Tests/GitWorkspaceScanToolTests.cs — add two new tests
• Phantom.Workspaces.Tools.Tests/GitWorkspaceDiscoveryToolTests.cs — add one new test

[JoshuaRowePhantom]

Verification passed

Checked: Commit